# Packages
# README
gowindows
Overview
gowindows is a Go library designed for remotely configuring and managing Windows-based systems.
Leveraging WinRM and SSH connections, gowindows provides a comprehensive set of functions to execute PowerShell commands, making it easy to automate tasks, manage users, groups, and more on remote Windows servers.
This library is especially useful when combined with tools like Terraform, enabling seamless integration into infrastructure as code workflows for Windows environments.
Usage
Single Client with an SSH Connection
package main
import (
"context"
"fmt"
"github.com/d-strobel/gowindows/connection/ssh"
"github.com/d-strobel/gowindows/windows/local/accounts"
)
func main() {
sshConfig := &ssh.Config{
Host: "winsrv",
Username: "vagrant",
Password: "vagrant",
}
// Create a new connection.
conn, err := ssh.NewConnection(sshConfig)
if err != nil {
panic(err)
}
// Create a client for the local accounts package.
c := accounts.NewClient(conn)
defer c.Connection.Close()
// Run the GroupRead function to retrieve a local Windows group.
group, err := c.GroupRead(context.Background(), accounts.GroupReadParams{Name: "Users"})
if err != nil {
panic(err)
}
// Print the user group.
fmt.Printf("User group: %+v", group)
}
Multi Client with a WinRM Connection
package main
import (
"context"
"fmt"
"github.com/d-strobel/gowindows"
"github.com/d-strobel/gowindows/connection/winrm"
"github.com/d-strobel/gowindows/windows/local/accounts"
)
func main() {
winrmConfig := &winrm.Config{
Host: "winsrv",
Username: "vagrant",
Password: "vagrant",
}
// Create a new connection.
conn, err := winrm.NewConnection(winrmConfig)
if err != nil {
panic(err)
}
// Create client for all subpackages.
c := gowindows.NewClient(conn)
defer c.Close()
// Run the GroupRead function to retrieve a local Windows group.
group, err := c.LocalAccounts.GroupRead(context.Background(), accounts.GroupReadParams{Name: "Users"})
if err != nil {
panic(err)
}
// Print the user group.
fmt.Printf("User group: %+v", group)
}
Development
Pre-commit
To ensure smooth execution in the pipeline and eliminate potential linting errors, it's highly advisable to integrate pre-commit hooks. These hooks can be effortlessly installed to streamline the process and maintain code quality standards.
You can find more details about pre-commit hooks on their official website: pre-commit.
Conventional Commits
gowindows follows the conventional commit guidelines. For more information, see conventionalcommits.org.
Testing
Unit tests
Run unit tests:
make test
Acceptance test
Prerequisites:
Boot the Vagrant machines:
make vagrant-up
Run acceptance tests:
make testacc
Destroy the Vagrant machines:
make vagrant-down
Third-Party libraries
- For the WinRM connection part, I rely on the library masterzen/winrm.
Inspirations
- hashicorp - terraform-provider-ad:
Hashicorp made a great start with the terraform-provider-ad. Currently, it seems that the provider is not actively maintained.
Beyond that, my goal is to split the terraform-provider into a library and a provider and extend its functionality with non Active-Directory systems.
License
This project is licensed under the Mozilla Public License Version 2.0.