Collect¶

This module provides many funcions and classes to collect data remotely and locally

Expect¶

class naghelp.Expect(spawn, login_steps=None, prompt=None, logout_cmd=None, logout_steps=None, context={}, timeout=30, expected_pattern='\S', unexpected_pattern='<timeout>', filter=None, *args, **kwargs)¶

Interact with a spawn command

Expect is a class that “talks” to other interactive programs. It is based on pexpect and is focused on running one or many commands. Expect is to be used when Telnet and Ssh are not applicable.

Parameters:

spawn (str) – The command to start and to communicate with
login_steps (list or tuple) – steps to execute to reach a prompt
prompt (str) – A pattern that matches the prompt
logout_cmd (str) – command to execute before closing communication (Default : None)
logout_steps (list or tuple) – steps to execute before closing communication (Default : None)
context (dict) – Dictionary that will be used in steps to .format() strings (Default : None)
timeout (int) – Maximum execution time (Default : 30)
expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found in methods that collect data (like run,mrun,get,mget,walk,mwalk…) if None, there is no test. By default, tests the result is not empty.
unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, it tests <timeout>.
filter (callable) – call a filter function with result, key, cmd parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : cmd is the command that generated the result and key the key in the dictionary for mrun, mget and mwalk. By Default, there is no filter.

On object creation, Expect will :

spawn the specified command (spawn)

follow login_steps

and wait for the specified prompt.

on object run() or mrun(), it will :

execute the specified command(s)

wait the specified prompt between each command

return command(s) output wihout prompt string

then close the interaction (see just below)

on close, Expect will :

execute the logout_cmd

follow logout_steps

finally terminate the spawned command

What are Steps ?

During login and logout, one can specify steps. A step is one or more pattern/answer tuples. The main tuple syntax is:
(
    (
        ( step1_pattern1, step1_answer1),
        ( step1_pattern2, step1_answer2),
        ...
    ),
    (
        ( step2_pattern1, step2_answer1),
        ( step2_pattern2, step2_answer2),
        ...
    ),
    ...
)
For a same step, Expect will search for any of the specified patterns, then will respond the corresponding answer. It will go to the next step only when one of the next step’s patterns is found. If not, will stay at the same step looking again for any of the patterns. In order to simplify tuple expression, if there is only one tuple in a level, the parenthesis can be removed. For answer, you have to specify a string : do not forget the newline otherwise you will get stuck. One can also use Expect.BREAK to stop following the steps, Expect.RESPONSE to raise an error with the found pattern as message. Expect.KILL does the same but also kills the spawned command.

Here are some login_steps examples :

The spawned command is just waiting a password:
(r'(?i)Password[^:]*: ','wwwpw\n')
The spawned command is waiting a login then a password:
(
    (r'(?i)Login[^:]*: ','www\n'),
    (r'(?i)Password[^:]*: ','wwwpassword\n')
)
The spawned command is waiting a login then a password, but may ask a question at login prompt:
(
    (
        (r'(?i)Are you sure to connect \?','yes'),
        (r'(?i)Login[^:]*: ','www\n')
    ),
    ('(?i)Password[^:]*: ','wwwpassword\n')
)
You can specify a context dictionary to Expect to format answers strings. With context = { 'user':'www','passwd':'wwwpassword' } login_steps becomes:
(
    (
        (r'(?i)Are you sure to connect \?','yes'),
        (r'(?i)Login[^:]*: ','{user}\n')
    ),
    ('(?i)Password[^:]*: ','{passwd}\n')
)

mrun(cmds, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, **kwargs)¶

Execute many commands at the same time

Runs a dictionary of commands at the specified prompt and then close the interaction. Timeout will not raise any error but will return None for the running command. It returns a dictionary where keys are the same as the cmds dict and the values are the commmands output.

Parameters:	cmds (dict or list of items) – The commands to be executed by the spawned command timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the interaction. expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found if None, there is no test. By default, use the value defined at object level. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, use the value defined at object level. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By default, use the filter defined at object level.
Returns:	The commands output
Return type:	`textops.DictExt`

Example

SSH with multiple commands:

e = Expect('ssh www@localhost',
            login_steps=('(?i)Password[^:]*: ','wwwpassword\n'),
            prompt=r'www@[^\$]*\$ ',
            logout_cmd='exit')
print e.mrun({'cur_dir':'pwd','big_files':'find . -type f -size +10000'})

Will return something like:

{
    'cur_dir' : '/home/www',
    'big_files' : 'bigfile1\nbigfile2\nbigfile3\n...'
}

Note

This example emulate Ssh class. Expect is better for non-standard commands that requires human interations.

run(cmd=None, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, **kwargs)¶

Execute one command

Runs a single command at the specified prompt and then close the interaction. Timeout will not raise any error but will return None. If you want to execute many commands without closing the interation, use with syntax.

Parameters:	cmd (str) – The command to be executed by the spawned command timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the interaction. expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found if None, there is no test. By default, use the value defined at object level. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, use the value defined at object level. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By default, use the filter defined at object level.
Returns:	The command output or None on timeout
Return type:	`textops.StrExt`

Examples

Doing a ssh through Expect:

e = Expect('ssh www@localhost',
            login_steps=('(?i)Password[^:]*: ','wwwpassword\n'),
            prompt=r'www@[^\$]*\$ ',
            logout_cmd='exit')
print e.run('ls -la')

Expect/ssh with multiple commands:

with Expect('ssh www@localhost',
            login_steps=('(?i)Password[^:]*: ','wwwpassword\n'),
            prompt=r'www@[^\$]*\$ ',
            logout_cmd='exit') as e:
    cur_dir = e.run('pwd').strip()
    big_files_full_path = e.run('find %s -type f -size +10000' % cur_dir)
print big_files_full_path

Note

These examples emulate Ssh class. Expect is better for non-standard commands that requires human interations.

Http¶

class naghelp.Http(expected_pattern='\S', unexpected_pattern='<timeout>', filter=None, *args, **kwargs)¶

Http class helper

This class helps to collect web pages.

Parameters:	host (str) – IP address or hostname to connect to port (int) – port number to use (Default : 80 TCP) timeout (int) – Time in seconds before raising an error or a None value

get(url, expected_pattern=0, unexpected_pattern=0, filter=0, *args, **kwargs)¶

get one URL

Parameters:	url (str) – The url to get timeout (int) – Time in seconds before raising an error or a None value
Returns:	The page or NoAttr if URL is reachable but returned a Http Error
Return type:	str

mget(urls, expected_pattern=0, unexpected_pattern=0, filter=0, *args, **kwargs)¶

Get multiple URLs at the same time

Parameters:	urls (dict) – The urls to get timeout (int) – Time in seconds before raising an error or a None value
Returns:	List of pages or NoAttr if not availables
Return type:	`textops.DictExt`

mpost(urls, expected_pattern=0, unexpected_pattern=0, filter=0, *args, **kwargs)¶

Post multiple URLs at the same time

Parameters:	urls (dict) – The urls to get timeout (int) – Time in seconds before raising an error or a None value
Returns:	List of pages or NoAttr if not availables
Return type:	`textops.DictExt`

post(url, expected_pattern=0, unexpected_pattern=0, filter=0, *args, **kwargs)¶

post one URL

Parameters:	url (str) – The url to get timeout (int) – Time in seconds before raising an error or a None value
Returns:	The page or NoAttr if URL is reachable but returned a Http Error
Return type:	str

Snmp¶

class naghelp.Snmp(host, community='public', version=None, timeout=30, port=161, user=None, auth_passwd=None, auth_protocol='', priv_passwd=None, priv_protocol='', object_identity_to_string=True, *args, **kwargs)¶

Snmp class helper

This class helps to collect OIDs from a remote snmpd server. One can issue some snmpget and/or snmpwalk. Protocols 1, 2c and 3 are managed. It uses pysnmp library.

Parameters:

host (str) – IP address or hostname to connect to
community (str) – community to use (For protocol 1 and 2c)
version (int) – protocol to use : None, 1,2,‘2c’ or 3 (Default: None). If None, it will use protocol 3 if a user is specified, 2c otherwise.
timeout (int) – Time in seconds before raising an error or a None value
port (int) – port number to use (Default : 161 UDP)
user (str) – protocol V3 authentication user
auth_passwd (str) – snmp v3 authentication password
auth_protocol (str) – snmp v3 auth protocol (‘md5’ or ‘sha’)
priv_passwd (str) – snmp v3 privacy password
priv_protocol (str) – snmp v3 privacy protocol (‘des’ or ‘aes’)

exists(oid_or_mibvar)¶

Return True if the OID exists

It return False if the OID does not exists or raise an exception if snmp server is unreachable

Parameters:	oid_or_mibvar (str or ObjectIdentity) – an OID path or a pysnmp ObjectIdentity
Returns:	True if OID exists
Return type:	bool

Examples

To collect a numerical OID:

>>> snmp = Snmp('demo.snmplabs.com')
>>> snmp.exists('1.3.6.1.2.1.1.1.0')
True
>>> snmp.exists('1.3.6.1.2.1.1.1.999')
False

get(oid_or_mibvar)¶

get one OID

Parameters:	oid_or_mibvar (str or ObjectIdentity) – an OID path or a pysnmp ObjectIdentity
Returns:	OID value. The python type depends on OID MIB type.
Return type:	`textops.StrExt` or int

Examples

To collect a numerical OID:

>>> snmp = Snmp('demo.snmplabs.com')
>>> snmp.get('1.3.6.1.2.1.1.1.0')
'SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'

To collect an OID with label form:

>>> snmp = Snmp('demo.snmplabs.com')
>>> snmp.get('iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0')
'SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'

To collect an OID with MIB symbol form:

>>> snmp = Snmp('demo.snmplabs.com')
>>> snmp.get(('SNMPv2-MIB', 'sysDescr', 0))
'SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'

mget(vars_oids)¶

Get multiple OIDs at the same time

This method is much more faster than doing multiple get() because it uses the same network request. In addition, one can request a range of OID. To build a range, just use a dash between to integers : this OID will be expanded with all integers in between : For instance, ‘1.3.6.1.2.1.1.2-4.1’ means : [ 1.3.6.1.2.1.1.2.1, 1.3.6.1.2.1.1.3.1, 1.3.6.1.2.1.1.4.1 ]

Parameters:	vars_oids (dict) – keyname/OID dictionary
Returns:	List of tuples (OID,value). Values type are int or `textops.StrExt`
Return type:	`textops.DictExt`

Example

>>> snmp = Snmp('demo.snmplabs.com')
>>> print snmp.mget({'uname':'1.3.6.1.2.1.1.0','other':'1.3.6.1.2.1.1.2-9.0'})  
{'uname' : 'SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m',
 'other' : ['value for 1.3.6.1.2.1.1.2.0', 'value for 1.3.6.1.2.1.1.3.0', etc... ] }

mwalk(vars_oids, ignore_errors=False)¶

Walk from multiple OID root pathes

Parameters:	vars_oids (dict) – keyname/OID root path dictionary
Returns:	A dictionary of list of tuples (OID,value). Values type are int or `textops.StrExt`
Return type:	`textops.DictExt`

Example

>>> snmp = Snmp('localhost')
>>> print snmp.mwalk({'node1' : '1.3.6.1.2.1.1.9.1.2', 'node2' : '1.3.6.1.2.1.1.9.1.3'})
{'node1': [('1.3.6.1.2.1.1.9.1.2.1', ObjectIdentity(ObjectIdentifier('1.3.6.1.6.3.10.3.1.1'))),
           ('1.3.6.1.2.1.1.9.1.2.2', ObjectIdentity(ObjectIdentifier('1.3.6.1.6.3.11.3.1.1')))
           ... ],
 'node2': [('1.3.6.1.2.1.1.9.1.3.1', 'The SNMP Management Architecture MIB.'),
           ('1.3.6.1.2.1.1.9.1.3.2', 'The MIB for Message Processing and Dispatching.'),
           ... ]}

normalize_oid(oid)¶

Normalize OID object in order to be used with pysnmp methods

Basically, it converts OID with a tuple form into a ObjectIdentity form, keeping other forms unchanged.

Parameters:	oid (str,tuple or ObjectIdentity) – The OID to normalize
Returns:	OID form that is ready to be used with pysnmp
Return type:	str or ObjectIdentity

Examples

>>> s=Snmp('demo.snmplabs.com')
>>> s.normalize_oid(('SNMPv2-MIB', 'sysDescr2', 0))
ObjectIdentity('SNMPv2-MIB', 'sysDescr2', 0)
>>> s.normalize_oid('1.3.6.1.2.1.1.1.0')
'1.3.6.1.2.1.1.1.0'

walk(oid_or_mibvar, ignore_errors=False)¶

Walk from a OID root path

Parameters:	oid_or_mibvar (str or ObjectIdentity) – an OID path or a pysnmp ObjectIdentity
Returns:	List of tuples (OID,value). Values type are int or `textops.StrExt`
Return type:	`textops.ListExt`

Example

>>> snmp = Snmp('localhost')
>>> for oid,val in snmp.walk('1.3.6.1.2.1.1'):  
...     print oid,'-->',val
...
1.3.6.1.2.1.1.1.0 --> SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m
1.3.6.1.2.1.1.2.0 --> 1.3.6.1.4.1.20408
     ...

Ssh¶

class naghelp.Ssh(host, user, password=None, timeout=30, auto_accept_new_host=True, prompt_pattern=None, get_pty=False, expected_pattern='\S', unexpected_pattern='<timeout>', filter=None, add_stderr=True, *args, **kwargs)¶

Ssh class helper

This class create a ssh connection in order to run one or many commands.

Parameters:

host (str) – IP address or hostname to connect to
user (str) – The username to use for login
password (str) – The password
timeout (int) – Time in seconds before raising an error or a None value
prompt_pattern (str) – None by Default. If defined, the way to run commands is to capture the command output up to the prompt pattern. If not defined, it uses paramiko exec_command() method (preferred way).
get_pty (bool) – Create a pty, this is useful for some ssh connection (Default: False)
expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found in methods that collect data (like run,mrun,get,mget,walk,mwalk…) if None, there is no test. By default, tests the result is not empty.
unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, it tests <timeout>.
filter (callable) – call a filter function with result, key, cmd parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : cmd is the command that generated the result and key the key in the dictionary for mrun, mget and mwalk. By Default, there is no filter.
add_stderr (bool) – If True, the stderr will be added at the end of results (Default: True)
port (int) – port number to use (Default : 0 = 22)
pkey (PKey) – an optional private key to use for authentication
key_filename (str) – the filename, or list of filenames, of optional private key(s) to try for authentication
allow_agent (bool) – set to False to disable connecting to the SSH agent
look_for_keys (bool) – set to False to disable searching for discoverable private key files in ~/.ssh/
compress (bool) – set to True to turn on compression
sock (socket) – an open socket or socket-like object (such as a .Channel) to use for communication to the target host
gss_auth (bool) – True if you want to use GSS-API authentication
gss_kex (bool) – Perform GSS-API Key Exchange and user authentication
gss_deleg_creds (bool) – Delegate GSS-API client credentials or not
gss_host (str) – The targets name in the kerberos database. default: hostname
banner_timeout (float) – an optional timeout (in seconds) to wait for the SSH banner to be presented.

mrun(cmds, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, **kwargs)¶

Execute many commands at the same time

Runs a dictionary of commands at the specified prompt and then close the connection. Timeout will not raise any error but will return None for the running command. It returns a dictionary where keys are the same as the cmds dict and the values are the commmands output.

Parameters:	cmds (dict or list of items) – The commands to be executed by remote host timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the connection. expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found if None, there is no test. By default, use the value defined at object level. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, use the value defined at object level. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By default, use the filter defined at object level.
Returns:	The commands output
Return type:	`textops.DictExt`

Example

SSH with multiple commands:

ssh = Ssh('localhost','www','wwwpassword')
print ssh.mrun({'cur_dir':'pwd','big_files':'find . -type f -size +10000'})

Will return something like:

{
    'cur_dir' : '/home/www',
    'big_files' : 'bigfile1\nbigfile2\nbigfile3\n...'
}

To be sure to have the commands order respected, use list of items instead of a dict:

ssh = Ssh('localhost','www','wwwpassword')
print ssh.mrun( (('cmd','./mycommand'),('cmd_err','echo $?')) )

run(cmd, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, **kwargs)¶

Execute one command

Runs a single command at the usual prompt and then close the connection. Timeout will not raise any error but will return None. If you want to execute many commands without closing the connection, use with syntax.

Parameters:	cmd (str) – The command to be executed timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the connection. expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found if None, there is no test. By default, use the value defined at object level. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, use the value defined at object level. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By default, use the filter defined at object level.
Returns:	The command output or None on timeout
Return type:	`textops.StrExt`

Examples

SSH with default login/password/prompt:

ssh = Ssh('localhost','www','wwwpassword')
print ssh.run('ls -la')

SSH with multiple commands (use with to keep connection opened). This is usefull when one command depend on another one:

with Ssh('localhost','www','wwwpassword') as ssh:
    cur_dir = ssh.run('pwd').strip()
    big_files_full_path = ssh.run('find %s -type f -size +10000' % cur_dir)
print big_files_full_path

run_channels(cmd, timeout=30, auto_close=True, **kwargs)¶

Execute one command

Runs a single command at the usual prompt and then close the connection. Timeout will not raise any error but will return None. If you want to execute many commands without closing the connection, use with syntax. This function returns 3 values : stdout dump, stderr dump and exit status. Pattern testing and filtering is not available in this method (see run() method if you want them)

Parameters:	cmd (str) – The command to be executed timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the connection.
Returns:	output on stdout, errors on stderr and exit status
Return type:	out (str), err (str), status (int)

Examples

SSH with default login/password/prompt:

ssh = Ssh('localhost','www','wwwpassword')
out, err, status =  ssh.run_channels('ls -la')
print 'out = %s\nerr = %s\nstatus=%s' % (out, err, status)

SSH with multiple commands (use with to keep connection opened). This is usefull when one command depend on another one:

with Ssh('localhost','www','wwwpassword') as ssh:
    cur_dir, err, status = ssh.run_channels('pwd').strip()
    if not err:
        big_files_full_path = ssh.run('find %s -type f -size +10000' % cur_dir)
print big_files_full_path

run_script(script, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, auto_strip=True, format_dict={}, **kwargs)¶

Execute a script

Returns:	The script output or None on timeout
Return type:	`textops.StrExt`

Telnet¶

class naghelp.Telnet(host, user, password=None, timeout=30, port=0, login_pattern=None, passwd_pattern=None, prompt_pattern=None, autherr_pattern=None, sleep=0, sleep_login=0, expected_pattern='\S', unexpected_pattern='<timeout>', filter=None, *args, **kwargs)¶

Telnet class helper

This class create a telnet connection in order to run one or many commands.

Parameters:

host (str) – IP address or hostname to connect to
user (str) – The username to use for login
password (str) – The password
timeout (int) – Time in seconds before raising an error or a None value
port (int) – port number to use (Default : 0 = 23)
login_pattern (str or list) – The pattern to recognize the login prompt (Default : login\s*:). One can specify a string, a re.RegexObject, a list of string or a list of re.RegexObject
passwd_pattern (str or list) – The pattern to recognize the password prompt (Default : Password\s*:). One can specify a string, a re.RegexObject, a list of string or a list of re.RegexObject
prompt_pattern (str) – The pattern to recognize the usual prompt (Default : [\r\n][^\s]*\s?[\$#>:]+\s). One can specify a string or a re.RegexObject.
autherr_pattern (str) – The pattern to recognize authentication error (Default : bad password|login incorrect|login failed|authentication error). One can specify a string or a re.RegexObject.
sleep (int) – Add delay in seconds before each write/expect
sleep_login (int) – Add delay in seconds before login
expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found in methods that collect data (like run,mrun,get,mget,walk,mwalk…) if None, there is no test. By default, tests the result is not empty.
unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, it tests <timeout>.
filter (callable) – call a filter function with result, key, cmd parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : cmd is the command that generated the result and key the key in the dictionary for mrun, mget and mwalk. By Default, there is no filter.

mrun(cmds, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, **kwargs)¶

Execute many commands at the same time

Runs a dictionary of commands at the specified prompt and then close the connection. Timeout will not raise any error but will return None for the running command. It returns a dictionary where keys are the same as the cmds dict and the values are the commmands output.

Parameters:	cmds (dict or list of items) – The commands to be executed by remote host timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the connection. expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found if None, there is no test. By default, use the value defined at object level. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, use the value defined at object level. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By default, use the filter defined at object level.
Returns:	The commands output
Return type:	`textops.DictExt`

Example

Telnet with multiple commands:

tn = Telnet('localhost','www','wwwpassword')
print tn.mrun({'cur_dir':'pwd','big_files':'find . -type f -size +10000'})

Will return something like:

{
    'cur_dir' : '/home/www',
    'big_files' : 'bigfile1\nbigfile2\nbigfile3\n...'
}

run(cmd, timeout=30, auto_close=True, expected_pattern=0, unexpected_pattern=0, filter=0, **kwargs)¶

Execute one command

Runs a single command at the usual prompt and then close the connection. Timeout will not raise any error but will return None. If you want to execute many commands without closing the connection, use with syntax.

Parameters:	cmd (str) – The command to be executed timeout (int) – A timeout in seconds after which the result will be None auto_close (bool) – Automatically close the connection. expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found if None, there is no test. By default, use the value defined at object level. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, use the value defined at object level. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By default, use the filter defined at object level.
Returns:	The command output or None on timeout
Return type:	`textops.StrExt`

Examples

Telnet with default login/password/prompt:

tn = Telnet('localhost','www','wwwpassword')
print tn.run('ls -la')

Telnet with custom password prompt (password in french), note the (?i) for the case insensitive:

tn = Telnet('localhost','www','wwwpassword',password_pattern=r'(?i)Mot de passe\s*:')
print tn.run('ls -la')

Telnet with multiple commands (use with to keep connection opened). This is usefull when one command depend on another one:

with Telnet('localhost','www','wwwpassword') as tn:
    cur_dir = tn.run('pwd').strip()
    big_files_full_path = tn.run('find %s -type f -size +10000' % cur_dir)
print big_files_full_path

Local commands¶

naghelp.runsh(cmd, context={}, timeout=30, expected_pattern='\\S', unexpected_pattern=None, filter=None, key='')¶

Run a local command with a timeout

If the command is a string, it will be executed within a shell.
If the command is a list (the command and its arguments), the command is executed without a shell.
If a context dict is specified, the command is formatted with that context (str.format())

Parameters:	cmd (str or a list) – The command to run context (dict) – The context to format the command to run (Optional) timeout (int) – The timeout in seconds after with the forked process is killed and TimeoutException is raised (Default : 30s). expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found. if None, there is no test. By default, tests the result is not empty. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, there is no test. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By Default, there is no filter. key (str) – a key string to appear in UnexpectedResultError if any.
Returns:	Command execution stdout as a list of lines.
Return type:	`textops.ListExt`

Note

It returns ONLY stdout. If you want to get stderr, you need to redirect it to stdout.

Examples

>>> for line in runsh('ls -lad /etc/e*'):
...     print line
...
-rw-r--r-- 1 root root  392 oct.   8  2013 /etc/eclipse.ini
-rw-r--r-- 1 root root  350 mai   21  2012 /etc/eclipse.ini_old
drwxr-xr-x 2 root root 4096 avril 13  2014 /etc/elasticsearch
drwxr-xr-x 3 root root 4096 avril 25  2012 /etc/emacs
-rw-r--r-- 1 root root   79 avril 25  2012 /etc/environment
drwxr-xr-x 2 root root 4096 mai    1  2012 /etc/esound

>>> print runsh('ls -lad /etc/e*').grep('eclipse').tostr()
-rw-r--r-- 1 root root  392 oct.   8  2013 /etc/eclipse.ini
-rw-r--r-- 1 root root  350 mai   21  2012 /etc/eclipse.ini_old

>>> l=runsh('LANG=C ls -lad /etc/does_not_exist')
>>> print l
[]
>>> l=runsh('LANG=C ls -lad /etc/does_not_exist 2>&1')
>>> print l
['ls: cannot access /etc/does_not_exist: No such file or directory']

naghelp.runshex(cmd, context={}, timeout=30, expected_pattern='\\S', unexpected_pattern=None, filter=None, key='', unexpected_stderr=True)¶

Run a local command with a timeout

If the command is a string, it will be executed within a shell.
If the command is a list (the command and its arguments), the command is executed without a shell.
If a context dict is specified, the command is formatted with that context (str.format())

Parameters:	cmd (str or a list) – The command to run context (dict) – The context to format the command to run (Optional) timeout (int) – The timeout in seconds after with the forked process is killed and TimeoutException is raised (Default : 30s). expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found. if None, there is no test. By default, tests the result is not empty. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, there is no test. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By Default, there is no filter. key (str) – a key string to appear in UnexpectedResultError if any. unexpected_stderr (bool) – When True (Default), it raises an error if stderr is not empty
Returns:	stdout, stderr, return code tuple
Return type:	tuple

Note

It returns ONLY stdout. If you want to get stderr, you need to redirect it to stdout.

naghelp.mrunsh(cmds, context={}, cmd_timeout=30, total_timeout=60, expected_pattern='\\S', unexpected_pattern=None, filter=None)¶

Run multiple local commands with timeouts

It works like runsh() except that one must provide a dictionary of commands. It will generate the same dictionary where values will be replaced by command execution output. It is possible to specify a by-command timeout and a global timeout for the whole dictionary.

Parameters:	cmds (dict) – dictionary where values are the commands to execute. If the command is a string, it will be executed within a shell. If the command is a list (the command and its arguments), the command is executed without a shell. If a context dict is specified, the command is formatted with that context (`str.format()`) context (dict) – The context to format the command to run cmd_timeout (int) – The timeout in seconds for a single command total_timeout (int) – The timeout in seconds for the all commands expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found. if None, there is no test. By default, tests the result is not empty. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, there is no test. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By Default, there is no filter.
Returns:	Dictionary where each value is the Command execution stdout as a list of lines.
Return type:	`textops.DictExt`

Note

Command execution returns ONLY stdout. If you want to get stderr, you need to redirect it to stdout.

Examples

>>> mrunsh({'now':'LANG=C date','quisuisje':'whoami'})
{'now': ['Wed Dec 16 11:50:08 CET 2015'], 'quisuisje': ['elapouya']}

naghelp.mrunshex(cmds, context={}, cmd_timeout=30, total_timeout=60, expected_pattern='\\S', unexpected_pattern=None, filter=None, unexpected_stderr=True)¶

Run multiple local commands with timeouts

It works like runshex() except that one must provide a dictionary of commands. It will generate the same dictionary where values will be replaced by command execution output. It is possible to specify a by-command timeout and a global timeout for the whole dictionary. stderr are store in <key>_stderr and return codes in <key>_rcode

Parameters:	cmds (dict) – dictionary where values are the commands to execute. If the command is a string, it will be executed within a shell. If the command is a list (the command and its arguments), the command is executed without a shell. If a context dict is specified, the command is formatted with that context (`str.format()`) context (dict) – The context to format the command to run cmd_timeout (int) – The timeout in seconds for a single command total_timeout (int) – The timeout in seconds for the all commands expected_pattern (str or regex) – raise UnexpectedResultError if the pattern is not found. if None, there is no test. By default, tests the result is not empty. unexpected_pattern (str or regex) – raise UnexpectedResultError if the pattern is found if None, there is no test. By default, there is no test. filter (callable) – call a filter function with `result, key, cmd` parameters. The function should return the modified result (if there is no return statement, the original result is used). The filter function is also the place to do some other checks : `cmd` is the command that generated the `result` and `key` the key in the dictionary for `mrun`, `mget` and `mwalk`. By Default, there is no filter. unexpected_stderr (bool) – When True (Default), it raises an error if stderr is not empty
Returns:	Dictionary where each value is the Command execution stdout as a list of lines.
Return type:	`textops.DictExt`

Note

Command execution returns ONLY stdout. If you want to get stderr, you need to redirect it to stdout.

Examples

>>> mrunsh({'now':'LANG=C date','quisuisje':'whoami'})
{'now': ['Wed Dec 16 11:50:08 CET 2015'], 'quisuisje': ['elapouya']}

Others¶

naghelp.search_invalid_port(ip, ports)¶

Returns the first invalid port encountered or None if all are reachable

Parameters:	ip (str) – ip address to test ports (str or list of int) – list of ports to test
Returns:	first invalid port encountered or None if all are reachable

Examples

>>> search_invalid_port('8.8.8.8','53')
(None)
>>> search_invalid_port('8.8.8.8','53,22,80')
22

Exceptions¶

exception naghelp.NotConnected¶

Exception raised when trying to collect data on an already close connection

After a run()/mrun() without a with: clause, the connection is automatically closed. Do not do another run()/mrun() in the row otherwise you will have the exception. Solution : use with:

exception naghelp.ConnectionError¶

Exception raised when trying to initialize the connection

It may come from bad login/password, bad port, inappropriate parameters and so on

exception naghelp.CollectError¶

Exception raised when a collect is unsuccessful

It may come from internal error from libraries pexpect/telnetlib/pysnmp. This includes some internal timeout exception.

exception naghelp.TimeoutError¶

Exception raised when a connection or a collect it too long to process

It may come from unreachable remote host, too long lasting commands, bad pattern matching on Expect/Telnet/Ssh for connection or prompt search steps.

exception naghelp.UnexpectedResultError¶

Exception raised when a command gave an unexpected result

This works with expected_pattern and unexpected_pattern available in some collecting classes.