KnownHosts

Known hosts backend.

cumin.backends.knownhosts.GRAMMAR_PREFIX = 'K'

str -- the prefix associate to this grammar, to register this backend into the general grammar. Required by the backend auto-loader in cumin.grammar.get_registered_backends().

exception cumin.backends.knownhosts.KnownHostsLineError

Bases: cumin.backends.InvalidQueryError

Custom exception class for invalid lines in SSH known hosts files.

with_traceback()

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

class cumin.backends.knownhosts.KnownHostsQuery(config)

Bases: cumin.backends.BaseQueryAggregator

KnownHostsQuery query builder.

The knownhosts backend allow to use Cumin taking advantage of existing SSH known hosts files that are not hashed. It allow to write arbitrarily complex queries with subgroups and boolean operators, but each item must be either the hostname itself, or using host expansion with the powerful ClusterShell.NodeSet.NodeSet syntax.

The typical use case for the knownhosts backend is when the known hosts file(s) are generated and kept updated by some external configuration manager or tool that is not yet supported as a backend for Cumin. It can also work as a fallback backend in case the primary backend is unavailable but the known hosts file(s) are still up to date.

__init__(config)

Known hosts query constructor, initialize the known hosts.

Parameters:according to parent cumin.backends.BaseQuery.__init__().

_aggregate_hosts(hosts, element_hosts, bool_operator)

static inherited Aggregate hosts according to their boolean operator.

Parameters:

• hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to update with the results in element_hosts according to the bool_operator. This object is updated in place by reference.
• element_hosts (ClusterShell.NodeSet.NodeSet) -- the additional hosts to aggregate to the results based on the bool_operator.
• bool_operator (str, None) -- the boolean operator to apply while aggregating the two NodeSet. It must be None when adding the first hosts.

_build(query_string)

Override parent method to lazy-loading the known hosts if needed.

Parameters:according to parent cumin.backends.BaseQuery._build().

_close_subgroup()

static inherited Handle subgroup closing.

_execute()

Override parent method to ensure to return only existing hosts.

Parameters:according to parent cumin.backends.BaseQuery._execute().

static _get_stack_element()

static inherited Return an empty stack element.

Returns:the dictionary with an empty stack element. Return type:dict

_load_known_hosts()

Load all known hosts file listed in the configuration.

_loop_stack(hosts, stack_element)

static inherited Loop the stack generated while parsing the query and aggregate the results.

Parameters:

• hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to be updated with the current stack element results. This object is updated in place by reference.
• stack_element (dict) -- the stack element to iterate.

_open_subgroup()

static inherited Handle subgroup opening.

_parse_token(token)

Concrete implementation of parent abstract method.

Parameters:according to parent cumin.backends.BaseQueryAggregator._parse_token().

execute(query_string)

static inherited Build and execute the query, return the NodeSet of FQDN hostnames that matches.

Parameters:query_string (str) -- the query string to be parsed and executed. Returns:with the FQDNs of the matching hosts. Return type:ClusterShell.NodeSet.NodeSet

grammar = Forward: ...

pyparsing.ParserElement -- load the grammar parser only once in a singleton-like way.

static parse_known_hosts_line()

Parse an SSH known hosts formatted line and extract the valid hostnames.

See the SSH_KNOWN_HOSTS FILE FORMAT` in ``man sshd for the details of the file format.

Parameters:

line (str) -- the line to parse.

Raises:

• KnownHostsSkippedLineError -- if the line is skipped.
• KnownHostsLineError -- if unable to parse the line.

Returns:

a set with the hostnames found in the given line.

Return type:

set

static parse_line_hosts()

Parse a comma-separated hostnamed from an SSH known hosts formatted line and extract the valid hostnames.

Parameters:line_hosts (str) -- the hostnames to parse. Returns:a tuple with two sets, the hostnames found in the given line and the hostnames skipped. Return type:tuple

exception cumin.backends.knownhosts.KnownHostsSkippedLineError

Bases: cumin.backends.InvalidQueryError

Custom exception class for skipped lines in SSH known hosts files.

with_traceback()

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

cumin.backends.knownhosts.grammar()

Define the query grammar.

Some query examples:

• Simple selection: host1.domain
• ClusterShell syntax for hosts expansion: host10[10-42].domain,host2010.other-domain
• ClusterShell syntax for hosts globbing: host10[10-42]*
• A complex selection: host100[1-5]* or (host10[30-40].domain and (host10[10-42].domain and not host33.domain))

Backus-Naur form (BNF) of the grammar:

<grammar> ::= <item> | <item> <boolean> <grammar>
   <item> ::= <hosts> | "(" <grammar> ")"
<boolean> ::= "and not" | "and" | "xor" | "or"

Given that the pyparsing library defines the grammar in a BNF-like style, for the details of the tokens not specified above check directly the source code.

Returns:the grammar parser. Return type:pyparsing.ParserElement

cumin.backends.knownhosts.query_class

Required by the backend auto-loader in cumin.grammar.get_registered_backends().

alias of cumin.backends.knownhosts.KnownHostsQuery