session(n) 1.3 session "Session"

NAME

session - open/close/control sessions

SYNOPSIS

package require libcisco

session open ?options? Host LinePw ?TacUsername TacUserPw?
session enable ?options? EnablePw ?TacUsername TacEnablePw?
session info InfoElement
session module ?options? Module ?LinePw? ?TacUsername TacUserPw?
session logger LogText
session close ?options?

DESCRIPTION

The session command performs one of several session operations.

COMMANDS

session open ?options? Host LinePw ?TacUsername TacUserPw?
Opens a session (e.g. telnet/ssh) with the target device.

Host is the IP address or hostname of the target device.

LinePw is the expected line password.

TacUsername is optional. It is the TACACS+/RADIUS username.

TacUserPw is optional. It is the TACACS/RADIUS login password.

Supported options are as follows:

-type { telnet | ssh }
Specifies the type of session to establish. Defaults to telnet.

-os { auto | ios | xdi | 1900 }
Specifies the expected operating system of the target system. An error is returned if the detected OS does not match that which is specified by this option, unless the option is auto. The "xdi" option refers to Catalyst code. Defaults to auto.

-retries [0-9]+
Specifies the maximum number of authentication attempts. Defaults to 3.

-pwprompt PwPrompt
This option is used to override the default expected "password:" prompt. The value for PwPrompt can be a simple string, or a regular expression. If it is a regular expression, the '^' and '$' anchors cannot be used.

-userprompt UserPrompt
This option is used to override the default expected "username:" prompt. The value for UserPrompt can be a simple string, or a regular expression. If it is a regular expression, the '^' and '$' anchors cannot be used.

-logfile Filename
This option enables logging to Filename. If the file already exists it will be overwritten. Defaults to no log file.

-logappend Filename
This option enables logging to Filename. If the file already exists it will be appended to. Defaults to no log file.

-verbose
Send output from the session to the stdout stream.

-timeout [0-9]+
By default, session open is expected to return within 30 seconds. This option can be used to override the default. The timeout value is expressed in seconds. The value supplied must be an integer.

-port [0-9]+
This option is used to override the default destination port (e.g. TCP/23) for the session. Defaults to 23 for telnet, and 22 for ssh.

--
End of options.


On success, session open returns an Expect spawn ID. More than likely, you will not need to use this ID unless you are very familiar with Expect. Even so, it is best to use the libcisco routines like sendCmd to interact with the session. Failure to do so will result in unpredictable results. On error a short text string is returned beginning with the string "err".

session enable ?options? EnablePw ?TacUsername TacEnablePw?
Place the device in privileged (enable) mode.

EnablePw is the enable password.

TacUsername is optional. It is the TACACS+/RADIUS username.

TacEnablePw is optional. It is the TACACS+/RADIUS enable password.

The following options are supported:

-retries [0-9]+
Specifies the maximum number of authentication attempts. Defaults to 3.

-pwprompt PwPrompt
This option is used to override the default expected "password:" prompt. The value for PwPrompt can be a simple string, or a regular expression. If it is a regular expression, the '^' and '$' anchors cannot be used.

-userprompt UserPrompt
This option is used to override the default expected "username:" prompt. The value for UserPrompt can be a simple string, or a regular expression. If it is a regular expression, the '^' and '$' anchors cannot be used.

-timeout [0-9]+
By default, session enable is expected to return within 30 seconds. This option can be used to override the default. The timeout value is expressed in seconds. The value supplied must be an integer.

--
End of options.


On success session enable returns 0. On error, a short text message is returned beginning with the string "err".

session info InfoElement
Returns information about the session. The type of information to be returned is determined by the value of InfoElement.

InfoElement is the information element to be returned. Valid options for InfoElement are as follows:

os
Returns the operating system of the device. One of three values--ios, xdi, or 1900.

mode
Returns the current mode of the target system. Valid return values are user for User EXEC mode, enable for Privileged EXEC mode, global for global configuration mode, line for line configuration mode, and interface for interface configuration mode.

lastid
Returns the last SessionId that was opened by calling session open.

cfgchange
Returns 1 if the configuration of the target device was changed during the current session. Returns 0 if the configuration has not been changed in the current session.


On success session info returns the requested information element. On error, a short text message is returned beginning with the string "err".

session module ?options? Module ?LinePw? ?TacUsername TacUserPw?
Session to a module on the target device (e.g. LANE).

Module identifies the module number to be session'd to.

LinePw is optional. It is the line password on the target module.

TacUsername is optional. It is the TACACS+/RADIUS username to be used during login.

TacUserPw is optional. It is the TACACS+/RADIUS password to be used during login.

Supported options are as follows:

-retries [0-9]+
Specifies the maximum number of authentication attempts. Defaults to 3.

-pwprompt PwPrompt
This option is used to override the default expected "password:" prompt. The value for PwPrompt can be a simple string, or a regular expression. If it is a regular expression, the '^' and '$' anchors cannot be used.

-userprompt UserPrompt
This option is used to override the default expected "username:" prompt. The value for UserPrompt can be a simple string, or a regular expression. If it is a regular expression, the '^' and '$' anchors cannot be used.

-timeout [0-9]+
By default, session enable is expected to return within 30 seconds. This option can be used to override the default. The timeout value is expressed in seconds. The value supplied must be an integer.

--
End of options.


On success session module returns 0. On error, a short text message is returned beginning with the string "err".

session logger LogText
session logger provides a means for updating a logfile that was opened via the -logfile or -logappend options to the session open command.

LogText is the string of text to be added to the logfile.

On success, session logger returns 0. On error, a short text message is returned beginning with the string "err".

session close ?options?
Close an open session.

Supported options are as follows:

-retries [0-9]+
Specifies the maximum number of attempts to exit. Defaults to 5.

-timeout [0-9]+
By default, session close is expected to return within 15 seconds. This option can be used to override the default. The timeout value is expressed in seconds. The value supplied must be an integer.

--
End of options.


On success, session close returns 0. On error, a short text message is returned beginning with the string "err".

EXAMPLE

The following code will open a telnet session to 192.168.1.1 logging in with a password of "cisco". It will then put the device in "enable" mode using a password of "san-fran". After issuing any number of commands on the device (...), the session is closed. For the sake of brevity and simplicity, no error checking is performed.

 
#!/bin/sh
# the next line restarts using the tclsh interpreter \ 
exec tclsh "$0" "$@"

package require libcisco
namespace import libcisco::*

session open 192.168.1.1 cisco
session enable san-fran
(...)
session close

AUTHOR

Andy Ziegelbein <
mailto:aziegelb@users.sourceforge.net>

SEE ALSO

sendCmd(n), ezset(n), ezget(n), ezdo(n)

KEYWORDS

session, open, enable, module, logger, close