awwan

package module
v0.12.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 5, 2024 License: GPL-3.0 Imports: 35 Imported by: 0

README

awwan

awwan is configuration management software, infrastructure as file and directory layout.

In other words, awwan is a command-line interface (CLI) to shell script, that can execute multiple lines of commands in local or remote server using shell or SSH.

Do you have a collection of shell scripts to manage one more similar server? Do you ever want to execute only part of your script? Are you get tired with learning others syntax and tools for provisioning your own server, while you need is a handful knowledge of shell script?

If yes, awwan is the right tools for you.

Features,

  • Encryption. Awwan can read and copy encrypted files.
  • Encrypted variables. Awwan can read and executed script that contains encrypted variables.
  • Dynamic script with variables. An awwan script is like shell script but can be executed in different remote servers with different values.
  • Dynamic script execution. Unlike shell script, awwan can select which lines to be executed, either by number or by range.
  • Provisioning in local environment using basic shell.
  • Provisioning in remote server using SSH and SFTP.

From the CLI perspective, awwan is feature complete.

Most enhancements and bug fixes probably in the web user interface with clear use cases and issues.

Feel free to open new feature or report a bug in our issue tracker.

Documentation

Project website.

Tour of awwan.

Changelog -- History of each awwan release.

Installation -- Link to download and/or install awwan manually from source code.

Manual page -- The manual page describe how to setup and use awwan.

Go documentation -- Go module documentation of awwan as library.

Development

Repository -- The repository of this software project.

Mailing list -- Place for discussion and sending patches.

Issues -- Place to open new issue or request for new feature.

Documentation

Overview

Package awwan provide the library for loading environment files, creating SSH client, and executing the script.

This documentation describe the design of awwan library. For documentation about awwan as CLI see the README.md on the root of repository.

Terminology

This section describe some terminologies that we use along when developing awwan. 

Workspace::
	The directory than contains ".ssh" directory with its "config"
	file.

Environment file::
	The name of environment file is static, set to "awwan.env".
	Its contains dynamic values to be applied to the script before
	executing them.

	The environment file is formatted using the git ini [1][2].

Script file::
	The file with .aww extension, its contains the statement to be
	executed.

Specifications

Awwan workspace is indicated by ".ssh" directory. User can pass the workspace directory when creating Awwan service or automatically lookup them from current working directory until "/". For example, if the current directory is "/home/ms/a/b/c/d", and ".ssh" directory exist on "b", then the Awwan workspace will be set to "/home/ms/a/b".

Once the .ssh directory found, user can execute the script in local or remote.

The Session type contains cache of the parsed Awwan environment files and SSH connections per host, to minimize re-reading "awwan.env" and re-creating new connection when executing different script on the same host.

The Script type contains list of statements to be executed later, either in local or remote.

References

[1] https://pkg.go.dev/git.sr.ht/~shulhan/pakakeh.go/lib/ini

[2] https://git-scm.com/docs/git-config#_configuration_file

Index

Examples

Constants

View Source 
const (
	CommandModeDecrypt = `decrypt`
	CommandModeEncrypt = `encrypt`
	CommandModeEnvGet  = `env-get`
	CommandModeEnvSet  = `env-set`
	CommandModeLocal   = `local`
	CommandModePlay    = `play`
	CommandModeServe   = `serve`
)

List of command available for program awwan.

View Source 
const DefListenAddress = `127.0.0.1:17600`

DefListenAddress default HTTP server address to serve WUI.

Variables

View Source 
var Version = `0.12.1`

Version current version of this module (library and program).

Functions

func ExecLocal added in v0.9.0 

func ExecLocal(ctx context.Context, req *ExecRequest, stmt *Statement) (err error)

ExecLocal execute the command with its arguments in local environment where the output and error send to os.Stdout and os.Stderr respectively.

If the statement command is "sudo" and stdin is non-nil, sudo will run with "-S" option to read password from stdin instead of from terminal.

The raw field must be used when generating Command to handle arguments with quotes.

Types

type Awwan added in v0.4.0 

type Awwan struct {
	BaseDir string
	// contains filtered or unexported fields
}

Awwan is the service that run script in local or remote. Awwan contains cache of sessions and cache of environment files.

func New 

func New(baseDir string) (aww *Awwan, err error)

New create and initialize new Awwan service using baseDir as the root of Awwan workspace. If baseDir is empty, it will set to current working directory.

func (*Awwan) Decrypt added in v0.8.0 

func (aww *Awwan) Decrypt(fileVault string) (filePlain string, err error)

Decrypt the file using private key from file "{{.BaseDir}}/.ssh/awwan.key". The encrypted file must have extension ".vault", otherwise it will return an error. The decrypted file output will be written in the same directory without the ".vault" extension in filePlain.

func (*Awwan) Encrypt added in v0.8.0 

func (aww *Awwan) Encrypt(file string) (fileVault string, err error)

Encrypt the file using private key from file "{{.BaseDir}}/.ssh/awwan.key". The encrypted file output will be on the same file path with ".vault" extension in fileVault.

func (*Awwan) EnvGet added in v0.10.0 

func (aww *Awwan) EnvGet(dir, key string) (val string, err error)

EnvGet get the value of environment based on the key. This method is similar to Session.Val when executed inside the script.

The dir parameter is optional, its define the directory where environment files will be loaded, recursively, from BaseDir to dir. If its empty default to the current directory.

The key parameter is using the "<section>:<sub>:<name>" format.

If the key is not exist it will return an empty string.

func (*Awwan) EnvKeys added in v0.12.0 

func (aww *Awwan) EnvKeys(path string) (keys []string, err error)

EnvKeys load environment files from BaseDir to path and return all its keys. The path is optional, default to BaseDir if its empty.

func (*Awwan) EnvSet added in v0.10.0 

func (aww *Awwan) EnvSet(file, key, val string) (err error)

EnvSet set the value in the environment file based on the key.

The file parameter point to "awwan.env" or INI formatted file.

The key is using the "<section>:<sub>:<name>" format.

func (*Awwan) Local added in v0.4.0 

func (aww *Awwan) Local(ctx context.Context, req *ExecRequest) (err error)

Local execute the script in the local machine using shell.

func (*Awwan) Play added in v0.4.0 

func (aww *Awwan) Play(ctx context.Context, req *ExecRequest) (err error)

Play execute the script in the remote machine using SSH.

func (*Awwan) Serve added in v0.4.0 

func (aww *Awwan) Serve(address string, isDev bool) (err error)

Serve start the web-user interface that serve awwan through HTTP.

type ExecRequest added in v0.10.0 

type ExecRequest struct {
	Mode      string `json:"mode"`
	Script    string `json:"script"`
	LineRange string `json:"line_range"`
	Content   []byte `json:"content"`
	// contains filtered or unexported fields
}

ExecRequest request for executing local or remote script. Each request define the Mode of execution, Script file to be executed, and the lineRange -- list of line numbers to be executed.

func NewExecRequest added in v0.10.0 

func NewExecRequest(mode, script, lineRange string) (req *ExecRequest, err error)

NewExecRequest create and initialize stdout and stderr to os.Stdout and os.Stderr.

type ExecResponse added in v0.10.0 

type ExecResponse struct {
	Mode      string `json:"mode"`
	Script    string `json:"script"`
	LineRange string `json:"line_range"`

	// ID of execution request that can be used to stream output or
	// got get full status.
	ID string `json:"id"`

	// BeginAt contains when the execution begin.
	BeginAt string `json:"begin_at"`

	// EndAt contains when the execution finished.
	EndAt string `json:"end_at"`

	Error string `json:"error"`

	Output []string `json:"output"`
	// contains filtered or unexported fields
}

ExecResponse contains the request and output of command execution, from ExecRequest.

func (*ExecResponse) Write added in v0.10.0 

func (execRes *ExecResponse) Write(out []byte) (n int, err error)

Write convert the raw output from execution into multiline string, and push it to field Output.

type Script added in v0.4.0 

type Script struct {
	// contains filtered or unexported fields
}

Script define the content of ".aww" file, line by line.

func NewScript added in v0.8.0 

func NewScript(ses *Session, path string) (script *Script, err error)

NewScript load the content of awwan script (".aww"), apply the value of session variables into the script content, and split it into Statements.

func ParseScript added in v0.8.0 

func ParseScript(ses *Session, path string, content []byte) (script *Script, err error)

ParseScript parse the script content by applying the session variables and splitting it into Statement.

Example 
var (
	envContent = `
[section]
key=value
`

	scriptContent = `
multiline \
command {{.Val "section::key"}}; \
end;
`

	ses = &Session{}

	s    *Script
	err  error
	stmt []byte
)

err = ses.loadRawEnv([]byte(envContent))
if err != nil {
	log.Fatal(err)
}

s, err = ParseScript(ses, `scriptContent`, []byte(scriptContent))
if err != nil {
	log.Fatal(err)
}

for _, stmt = range s.rawLines {
	fmt.Printf("%s\n", stmt)
}

Output:


multiline command value; end;

type Session added in v0.4.0 

type Session struct {
	BaseDir   string
	ScriptDir string

	SSHKey  string // The value of "IdentityFile" in SSH config.
	SSHUser string // The value of "User" in SSH config.
	SSHHost string // The value of "Hostname" in configuration.
	SSHPort string // The value of "Port" in configuration.
	// contains filtered or unexported fields
}

Session manage environment and SSH client.

func NewSession added in v0.4.0 

func NewSession(aww *Awwan, sessionDir string) (ses *Session, err error)

NewSession create and initialize the new session based on Awwan base directory and the session directory.

func (*Session) Copy added in v0.4.0 

func (ses *Session) Copy(req *ExecRequest, stmt *Statement) (err error)

Copy file in local system.

func (*Session) Get added in v0.4.0 

func (ses *Session) Get(stmt *Statement) (err error)

Get copy file from remote to local.

func (*Session) Put added in v0.4.0 

func (ses *Session) Put(ctx context.Context, req *ExecRequest, stmt *Statement) (err error)

Put copy file from local to remote system.

func (*Session) Subs added in v0.4.0 

func (ses *Session) Subs(secName string) (subs []*ini.Section)

Subs return list of sub sections that have the same section name.

func (*Session) SudoCopy added in v0.4.0 

func (ses *Session) SudoCopy(ctx context.Context, req *ExecRequest, stmt *Statement) (err error)

SudoCopy copy file in local system using sudo.

func (*Session) SudoGet added in v0.4.0 

func (ses *Session) SudoGet(ctx context.Context, req *ExecRequest, stmt *Statement) (err error)

SudoGet copy file from remote, that may not readable by remote user, to local using sudo. If the owner and/or mode is set, it will also applied using sudo on local host, after the file has been retrieved.

func (*Session) SudoPut added in v0.4.0 

func (ses *Session) SudoPut(ctx context.Context, req *ExecRequest, stmt *Statement) (err error)

SudoPut copy file from local to remote using sudo.

func (*Session) Val added in v0.4.0 

func (ses *Session) Val(keyPath string) (val string)

Val return the last variable value defined in key path. It will panic if the value is empty.

func (*Session) Vals added in v0.4.0 

func (ses *Session) Vals(keyPath string) (list []string)

Vals return all variable values as slice of string. It will panic if the no variables found.

func (*Session) Vars added in v0.4.0 

func (ses *Session) Vars(path string) (vars map[string]string)

Vars return all variables in section and/or subsection as map of string. It will panic if the no variables found.

type Statement added in v0.4.0 

type Statement struct {
	// contains filtered or unexported fields
}

Statement contains parsed raw line from the script.

func ParseStatement added in v0.4.0 

func ParseStatement(raw []byte) (stmt *Statement, err error)

ParseStatement create and initialize new Statement from raw line. It will return nil if raw line is empty.

func (*Statement) String added in v0.4.0 

func (stmt *Statement) String() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
awwan
awwan is command line interface to configure and manage remote system through SSH connection.
 awwan is command line interface to configure and manage remote system through SSH connection.
Package internal provide internal types and functions for building and developing awwan, not consumed by user nor the main program.
 Package internal provide internal types and functions for building and developing awwan, not consumed by user nor the main program.
cmd/awwan-internal
Program awwan-internal provides internal commands for developing and building awwan.
 Program awwan-internal provides internal commands for developing and building awwan.
cmd/www-awwan
Program www-awwan serve the awwan.org website.
 Program www-awwan serve the awwan.org website.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.