session(n) 1.0 session "Session"

NAME

session - Control sessions with remote Cisco network devices.

SYNOPSIS

package require libcisco

session open ?options? Host LinePw ?Username UserPw?
session enable ?options? ?SessionId? PwList
session module ?options? ?SessionId? Module ?LinePw? ?Username UserPw?
session logger ?SessionId? LogText
session close ?SessionId?

DESCRIPTION

The session command performs one of several session operations.

session open ?options? Host LinePw ?Username UserPw?
Opens a session with the device specified by Host. Once the session is established, a "password:" or "username:" prompt (not case sensitive) is expected. If a "password:" prompt is detected, the password specified by LinePw will be sent. On the other hand, if a "username:" prompt is detected, the username associated with Username will be sent. Thereafter, a "password:" prompt will be expected and upon detection, the password specified by UserPw will be sent instead of LinePw. If the attempted password fails, it will be retried up to 3 times or until the remote device closes the connection, whichever comes first. Supported options are as follows:

-type Type {telnet | ssh}
-os Os {auto | ios | xdi | 1900}
-retries Retries {[0-9]+}
-pwprompt PwPrompt
-userprompt UserPrompt
-logfile Filename
-logappend Filename
-verbose
-timeout Timeout {[0-9]+}
-port TcpPort {[0-9]+}
-- (end of options)

The type of session to be established may be explicitly set using the -type option. Valid values for Type are telnet and ssh (future). If no type is specified, it will default to telnet.

The -os option is used to explicitly set the expected operating system of the target device. Valid options for Os are auto, ios, xdi (CatCode), and 1900. Os defaults to auto. If an operating system is explicilty specified, the command will return an error if the detected OS is different from that which is specified by the Os option.

The -retries option controls how many times a password will be attempted during login before returning an error. Retries defaults to 3.

The -pwprompt option provides a means for overriding the default expected password prompt of "password:". If the target device has been configured to use a custom prompt (e.g. "Enter your PASSCODE:") by AAA or some other means, it will be necessary to specify that prompt using this option.

In the same manner as -pwprompt, the -userprompt may be used to override the default expected username prompt of "username:". The PwPrompt and UserPrompt may be a simple string, or a regular expression (note: the pattern matcher is not case sensitive).

If a Filename is specified with either the -logfile or -logappend options, a log file will be generated for the session. All output from the session will be logged to Filename until a call is made to session close. The -logfile option will overwrite an existing Filename if it exists. The -logappend option will append to Filename if it already exists.

The -verbose option is a boolean option--it takes no arguments. Session output is normally suppressed or logged to a file using the -logfile and -logappend options. If the -verbose option is specified, output from the session will be written to the stdout stream. The stdout stream is typically your console or xterm.

The session open command is expected to complete within 30 seconds by default. On high latency, heavily loaded, or unreliable WAN links, 30 seconds may not be a sufficient amount of time. The -timeout option may be used to specify a different timeout value.

The -port option is used to override the default destination TCP port number (telnet default: 23). For instance, in order to login through an access server (a.k.a. terminal concentrator, terminal server) which is directly connected to a console port, a different destination TCP port will most likely need to be specified (e.g. 2001).

On success, session open returns a unique SessionId. The use of the returned SessionId is optional and needed only if multiple sessions will be opened simultaneously within the same interpreter. On error a short text string is returned beginning with the string "err".

session enable ?options? ?SessionId? PwList
The session enable command is used to put the session in privileged (enable) mode. If multiple sessions have been opened, SessionId should be explicitly specified; otherwise, session enable will operate on the last session to be opened. PwList is a Tcl list of one or more passwords to be attempted. The following options are supported:

-retries Retries {[0-9]+}
-pwprompt PwPrompt
-timeout Timeout {[0-9]+}
-- (end of options)

The -retries option controls the number of times a password in PwList will be attempted before moving to the next password in PwList or returning an error if all passwords have been attempted. The default number of attempts is 3.

The -pwprompt option provides a means for overriding the default expected password prompt of "password:". If the target device has been configured to use a custom prompt (e.g. "Enter your PASSCODE:") by AAA or some other means, it will be necessary to specify that prompt using this option. PwPrompt may be a simple string or a regular expression (note: the pattern matcher is not case sensitive).

The session enable command is expected to complete within 30 seconds by default. On high latency, heavily loaded, or unreliable WAN links, 30 seconds may not be a sufficient amount of time. The -timeout option may be used to specify a different timeout value.

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

session module ?options? ?SessionId? Module ?LinePw? ?Username UserPw?
The session module command will session to the module specified by Module (this command is intended for devices running Catalyst Code only). Once the session is established, a "password:" or "username:" prompt (not case sensitive) is expected. If a "password:" prompt is detected, the password specified by LinePw will be sent. On the other hand, if a "username:" prompt is detected, the username associated with Username will be sent. Thereafter, a "password:" prompt will be expected and upon detection, the password specified by UserPw will be sent instead of LinePw. UserPw, Username, and LinePw are optional values. If they are left unspecified, the same values that were used to open the session with the call to session open will be used. If the attempted password fails, it will be retried up to 3 times or until the remote device closes the connection, whichever comes first. Supported options are as follows:

-retries Retries {[0-9]+}
-pwprompt PwPrompt
-userprompt UserPrompt
-timeout Timeout {[0-9]+}
-- (end of options)

The -retries option controls how many times a password will be attempted during login before returning an error. Retries defaults to 3.

The -pwprompt option provides a means for overriding the default expected password prompt of "password:". If the target device has been configured to use a custom prompt (e.g. "Enter your PASSCODE:") by AAA or some other means, it will be necessary to specify that prompt using this option. PwPrompt may be a simple string or a regular expression (note: the pattern matcher is not case sensitive).

In the same manner as -pwprompt, the -userprompt may be used to override the default expected username prompt of "username:". The PwPrompt and UserPrompt may be a simple string, or a regular expression (note: the pattern matcher is not case sensitive).

The session module command is expected to complete within 30 seconds by default. On high latency, heavily loaded, or unreliable WAN links, 30 seconds may not be a sufficient amount of time. The -timeout option may be used to specify a different timeout value.

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

session logger ?SessionId? 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. If no SessionId is specified, LogText will be logged to the last session to be opened. If no logfile was opened by session open, this command will return success but will have no effect.

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

session close ?SessionId?
The session close command will close a session that was opened using the session open command. The command works by repeatedly sending the string "exit" to the target device until an end-of-file (EOF) is detected. If multiple sessions have been opened, the last session to be opened will be closed if no SessionId is specified. Supported options are as follows:

-retries Retries {[0-9]+}
-timeout Timeout {[0-9]+}
-- (end of options)

The -retries option controls the maximum number of times the "exit" command will be issued on the target device. If an EOF has not been detected after issuing "exit" Retries times, the session will be terminated by sending a SIGHUP to the spawned process (telnet or ssh). The default number of retries is 5.

The session close command is expected to complete within 15 seconds by default. On high latency, heavily loaded, or unreliable WAN links, 15 seconds may not be a sufficient amount of time. The -timeout option may be used to specify a different timeout value.

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.

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

SEE ALSO

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

KEYWORDS

session, open, enable, module, logger, close