The session command performs one of several session operations.
session open ?options? HostLinePw ?UsernameUserPw?
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:
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:
-retriesRetries {[0-9]+} -pwpromptPwPrompt -timeoutTimeout {[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".
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:
-retriesRetries {[0-9]+} -pwpromptPwPrompt -userpromptUserPrompt -timeoutTimeout {[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:
-retriesRetries {[0-9]+} -timeoutTimeout {[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