package ssh_config

Import Path
	github.com/kevinburke/ssh_config (on go.dev)

Dependency Relation
	imports 13 packages, and imported by one package


Involved Source Files

	
		Package ssh_config provides tools for manipulating SSH config files.

		Importantly, this parser attempts to preserve comments in a given file, so
		you can manipulate a `ssh_config` file from a program, if your heart desires.

		The Get() and GetStrict() functions will attempt to read values from
		$HOME/.ssh/config, falling back to /etc/ssh/ssh_config. The first argument is
		the host name to match on ("example.com"), and the second argument is the key
		you want to retrieve ("Port"). The keywords are case insensitive.

				port := ssh_config.Get("myhost", "Port")

		You can also manipulate an SSH config file and then print it or write it back
		to disk.

			f, _ := os.Open(filepath.Join(os.Getenv("HOME"), ".ssh", "config"))
			cfg, _ := ssh_config.Decode(f)
			for _, host := range cfg.Hosts {
				fmt.Println("patterns:", host.Patterns)
				for _, node := range host.Nodes {
					fmt.Println(node.String())
				}
			}

			// Write the cfg back to disk:
			fmt.Println(cfg.String())

		BUG: the Match directive is currently unsupported; parsing a config with
		a Match directive will trigger an error.

	      lexer.go
	      parser.go
	      position.go
	      token.go
	      validators.go


Code Examples

	
		package main
		
		import (
			"fmt"
			"github.com/kevinburke/ssh_config"
			"strings"
		)
		
		func main() {
			var config = `
		Host *.example.com
		  Compression yes
		`
		
			cfg, _ := ssh_config.Decode(strings.NewReader(config))
			val, _ := cfg.Get("test.example.com", "Compression")
			fmt.Println(val)
		}


	
		package main
		
		import (
			"fmt"
			"github.com/kevinburke/ssh_config"
		)
		
		func main() {
			fmt.Println(ssh_config.Default("Port"))
			fmt.Println(ssh_config.Default("UnknownVar"))
		}


	
		package main
		
		import (
			"fmt"
			"github.com/kevinburke/ssh_config"
		)
		
		func main() {
			pat, _ := ssh_config.NewPattern("test.*.example.com")
			host := &ssh_config.Host{Patterns: []*ssh_config.Pattern{pat}}
			fmt.Println(host.Matches("test.stage.example.com"))
			fmt.Println(host.Matches("othersubdomain.example.com"))
		}


	
		package main
		
		import (
			"fmt"
			"github.com/kevinburke/ssh_config"
		)
		
		func main() {
			pat, _ := ssh_config.NewPattern("*")
			host := &ssh_config.Host{Patterns: []*ssh_config.Pattern{pat}}
			fmt.Println(host.Matches("test.stage.example.com"))
			fmt.Println(host.Matches("othersubdomain.any.any"))
		}




Package-Level Type Names (total 16, in which 9 are exported)


	/* sort exporteds by:  |  */
	
		Config represents an SSH config file.

		
			
				A list of hosts to match against. The file begins with an implicit
				"Host *" declaration matching all hosts.

			
		
			
				Get finds the first value in the configuration that matches the alias and
				contains key. Get returns the empty string if no value was found, or if the
				Config contains an invalid conditional Include value.

				The match for key is case insensitive.

			( T) MarshalText() ([]byte, error)
			
				String returns a string representation of the Config file.

		
			 T : encoding.TextMarshaler
			 T : expvar.Var
			 T : fmt.Stringer
			
		
			func Decode(r io.Reader) (*Config, error)
			
		
			


	
		Empty is a line in the config file that contains only whitespace or comments.

		
			Comment string
			
		
			
				Pos returns e's Position.

			
				String prints e as it was parsed in the config file.

		
			*T : Node
			*T : expvar.Var
			*T : fmt.Stringer
			


	
		Host describes a Host directive and the keywords that follow it.

		
			
				EOLComment is the comment (if any) terminating the Host line.

			
				A Node is either a key/value pair or a comment line.

			
				A list of host patterns that should match this host.

			
		
			
				Matches returns true if the Host matches for the given alias. For
				a description of the rules that provide a match, see the manpage for
				ssh_config.

			
				String prints h as it would appear in a config file. Minor tweaks may be
				present in the whitespace in the printed file.

		
			*T : expvar.Var
			*T : fmt.Stringer
			


	
		Include holds the result of an Include directive, including the config files
		that have been parsed as part of that directive. At most 5 levels of Include
		statements will be parsed.

		
			
				Comment is the contents of any comment at the end of the Include
				statement.

			
		
			
				Get finds the first value in the Include statement matching the alias and the
				given key.

			
				Pos returns the position of the Include directive in the larger file.

			
				String prints out a string representation of this Include directive. Note
				included Config files are not printed as part of this representation.

		
			*T : Node
			*T : expvar.Var
			*T : fmt.Stringer
			
		
			func NewInclude(directives []string, hasEquals bool, pos Position, comment string, system bool, depth uint8) (*Include, error)


	
		KV is a line in the config file that contains a key, a value, and possibly
		a comment.

		
			Comment string
			Key string
			Value string
			
		
			
				Pos returns k's Position.

			
				String prints k as it was parsed in the config file. There may be slight
				changes to the whitespace between values.

		
			*T : Node
			*T : expvar.Var
			*T : fmt.Stringer
			


	
		Node represents a line in a Config.

		
			( T) Pos() Position
			( T) String() string
		
			*Empty
			*Include
			*KV
		
			 T : expvar.Var
			 T : fmt.Stringer
			


	
		Pattern is a pattern in a Host declaration. Patterns are read-only values;
		create a new one with NewPattern().

		
			
		
			
				String prints the string representation of the pattern.

		
			 T : expvar.Var
			 T : fmt.Stringer
			
		
			func NewPattern(s string) (*Pattern, error)
		
			


	
		Position of a document element within a SSH document.

		Line and Col are both 1-indexed positions for the element's line number and
		column number, respectively.  Values of zero or less will cause Invalid(),
		to return true.

		
			
				// column within the line

			
				// line within the document

		
			
				Invalid returns whether or not the position is valid (i.e. with negative or
				null values)

			
				String representation of the position.
				Displays 1-indexed line and column numbers.

		
			 T : expvar.Var
			 T : fmt.Stringer
			
		
			func (*Empty).Pos() Position
			func (*Include).Pos() Position
			func (*KV).Pos() Position
			func Node.Pos() Position
		
			func NewInclude(directives []string, hasEquals bool, pos Position, comment string, system bool, depth uint8) (*Include, error)


	
		UserSettings checks ~/.ssh and /etc/ssh for configuration files. The config
		files are parsed and cached the first time Get() or GetStrict() is called.

		
			IgnoreErrors bool
			
		
			
				Get finds the first value for key within a declaration that matches the
				alias. Get returns the empty string if no value was found, or if IgnoreErrors
				is false and we could not parse the configuration file. Use GetStrict to
				disambiguate the latter cases.

				The match for key is case insensitive.

			
				GetStrict finds the first value for key within a declaration that matches the
				alias. If key has a default value and no matching configuration is found, the
				default will be returned. For more information on default values and the way
				patterns are matched, see the manpage for ssh_config.

				error will be non-nil if and only if a user's configuration file or the
				system configuration file could not be parsed, and u.IgnoreErrors is false.

		
			
		
			  var DefaultUserSettings *UserSettings


	


Package-Level Functions (total 27, in which 6 are exported)


	
		Decode reads r into a Config, or returns an error if r could not be parsed as
		an SSH config file.


	
		Default returns the default value for the given keyword, for example "22" if
		the keyword is "Port". Default returns the empty string if the keyword has no
		default, or if the keyword is unknown. Keyword matching is case-insensitive.

		Default values are provided by OpenSSH_7.4p1 on a Mac.


	
		Get finds the first value for key within a declaration that matches the
		alias. Get returns the empty string if no value was found, or if IgnoreErrors
		is false and we could not parse the configuration file. Use GetStrict to
		disambiguate the latter cases.

		The match for key is case insensitive.

		Get is a wrapper around DefaultUserSettings.Get.


	
		GetStrict finds the first value for key within a declaration that matches the
		alias. If key has a default value and no matching configuration is found, the
		default will be returned. For more information on default values and the way
		patterns are matched, see the manpage for ssh_config.

		error will be non-nil if and only if a user's configuration file or the
		system configuration file could not be parsed, and u.IgnoreErrors is false.

		GetStrict is a wrapper around DefaultUserSettings.GetStrict.


	
		NewInclude creates a new Include with a list of file globs to include.
		Configuration files are parsed greedily (e.g. as soon as this function runs).
		Any error encountered while parsing nested configuration files will be
		returned.


	
		NewPattern creates a new Pattern for matching hosts. NewPattern("*") creates
		a Pattern that matches all hosts.

		From the manpage, a pattern consists of zero or more non-whitespace
		characters, `*' (a wildcard that matches zero or more characters), or `?' (a
		wildcard that matches exactly one character). For example, to specify a set
		of declarations for any host in the ".co.uk" set of domains, the following
		pattern could be used:

			Host *.co.uk

		The following pattern would match any host in the 192.168.0.[0-9] network range:

			Host 192.168.0.?


	


Package-Level Variables (total 7, in which 2 are exported)


	
		DefaultUserSettings is the default UserSettings and is used by Get and
		GetStrict. It checks both $HOME/.ssh/config and /etc/ssh/ssh_config for keys,
		and it will return parse errors (if any) instead of swallowing them.


	
		ErrDepthExceeded is returned if too many Include directives are parsed.
		Usually this indicates a recursive loop (an Include directive pointing to the
		file it contains).


	


Package-Level Constants (total 10, none are exported)