pxssh - control an SSH session — Pexpect 4.2.1 documentation

# pxssh - control an SSH session

This class extends pexpect.spawn to specialize setting up SSH connections. This adds methods for login, logout, and expecting the shell prompt.

PEXPECT LICENSE

> This license is approved by the OSI and FSF as GPL-compatible.
>   http://opensource.org/licenses/isc-license.txt

> Copyright (c) 2012, Noah Spurrier <noah@noah.org> PERMISSION TO USE, COPY, MODIFY, AND/OR DISTRIBUTE THIS SOFTWARE FOR ANY PURPOSE WITH OR WITHOUT FEE IS HEREBY GRANTED, PROVIDED THAT THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE APPEAR IN ALL COPIES. THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class `pexpect.pxssh.` `ExceptionPxssh`(value)

  Raised for pxssh exceptions.

## pxssh class

class `pexpect.pxssh.` `pxssh`(timeout=30, maxread=2000, searchwindowsize=None, logfile=None, cwd=None, env=None, ignore_sighup=True, echo=True, options={}, encoding=None, codec_errors='strict')

  This class extends pexpect.spawn to specialize setting up SSH connections. This adds methods for login, logout, and expecting the shell prompt. It does various tricky things to handle many situations in the SSH login process. For example, if the session is your first login, then pxssh automatically accepts the remote certificate; or if you have public key authentication setup then pxssh won’t wait for the password prompt.

  pxssh uses the shell prompt to synchronize output from the remote host. In order to make this more robust it sets the shell prompt to something more unique than just $ or #. This should work on most Borne/Bash or Csh style shells.

  Example that runs a few commands on a remote server and prints the result:

      from pexpect import pxssh
      import getpass
      try:
          s = pxssh.pxssh()
          hostname = raw_input('hostname: ')
          username = raw_input('username: ')
          password = getpass.getpass('password: ')
          s.login(hostname, username, password)
          s.sendline('uptime')   # run a command
          s.prompt()             # match the prompt
          print(s.before)        # print everything before the prompt.
          s.sendline('ls -l')
          s.prompt()
          print(s.before)
          s.sendline('df')
          s.prompt()
          print(s.before)
          s.logout()
      except pxssh.ExceptionPxssh as e:
          print("pxssh failed on login.")
          print(e)

  Example showing how to specify SSH options:

      from pexpect import pxssh
      s = pxssh.pxssh(options={
                          "StrictHostKeyChecking": "no",
                          "UserKnownHostsFile": "/dev/null"})
      ...

  Note that if you have ssh-agent running while doing development with pxssh then this can lead to a lot of confusion. Many X display managers (xdm, gdm, kdm, etc.) will automatically start a GUI agent. You may see a GUI dialog box popup asking for a password during development. You should turn off any key agents during testing. The ‘force_password’ attribute will turn off public key authentication. This will only work if the remote SSH server is configured to allow password logins. Example of using ‘force_password’ attribute:

      s = pxssh.pxssh()
      s.force_password = True
      hostname = raw_input('hostname: ')
      username = raw_input('username: ')
      password = getpass.getpass('password: ')
      s.login (hostname, username, password)

  `__init__`(timeout=30, maxread=2000, searchwindowsize=None, logfile=None, cwd=None, env=None, ignore_sighup=True, echo=True, options={}, encoding=None, codec_errors='strict')
  `PROMPT`

    The regex pattern to search for to find the prompt. If you call `login()` with `auto_prompt_reset=False`, you must set this attribute manually.

  `force_password`

    If this is set to True, public key authentication is disabled, forcing the server to ask for a password. Note that the sysadmin can disable password logins, in which case this won’t work.

  `options`

    The dictionary of user specified SSH options, eg, `options = dict(StrictHostKeyChecking="no", UserKnownHostsFile="/dev/null")`

  `login`(server, username, password='', terminal_type='ansi', original_prompt='[#$]', login_timeout=10, port=None, auto_prompt_reset=True, ssh_key=None, quiet=True, sync_multiplier=1, check_local_ip=True)

    This logs the user into the given server.

    It uses ‘original_prompt’ to try to find the prompt right after login. When it finds the prompt it immediately tries to reset the prompt to something more easily matched. The default ‘original_prompt’ is very optimistic and is easily fooled. It’s more reliable to try to match the original prompt as exactly as possible to prevent false matches by server strings such as the “Message Of The Day”. On many systems you can disable the MOTD on the remote server by creating a zero-length file called `~/.hushlogin` on the remote server. If a prompt cannot be found then this will not necessarily cause the login to fail. In the case of a timeout when looking for the prompt we assume that the original prompt was so weird that we could not match it, so we use a few tricks to guess when we have reached the prompt. Then we hope for the best and blindly try to reset the prompt to something more unique. If that fails then login() raises an `ExceptionPxssh` exception.

    In some situations it is not possible or desirable to reset the original prompt. In this case, pass `auto_prompt_reset=False` to inhibit setting the prompt to the UNIQUE_PROMPT. Remember that pxssh uses a unique prompt in the `prompt()` method. If the original prompt is not reset then this will disable the `prompt()` method unless you manually set the `PROMPT` attribute.

  `logout`()

    Sends exit to the remote shell.

    If there are stopped jobs then this automatically sends exit twice.

  `prompt`(timeout=-1)

    Match the next shell prompt.

    This is little more than a short-cut to the `expect()` method. Note that if you called `login()` with `auto_prompt_reset=False`, then before calling `prompt()` you must set the `PROMPT` attribute to a regex that it will use for matching the prompt.

    Calling `prompt()` will erase the contents of the `before` attribute even if no prompt is ever matched. If timeout is not given or it is set to -1 then self.timeout is used.

    Returns: | True if the shell prompt was matched, False if the timeout was reached.

  `sync_original_prompt`(sync_multiplier=1.0)

    This attempts to find the prompt. Basically, press enter and record the response; press enter again and record the response; if the two responses are similar then assume we are at the original prompt. This can be a slow function. Worst case with the default sync_multiplier can take 12 seconds. Low latency connections are more likely to fail with a low sync_multiplier. Best case sync time gets worse with a high sync multiplier (500 ms with default).

  `set_unique_prompt`()

    This sets the remote prompt to something more unique than `#` or `$`. This makes it easier for the `prompt()` method to match the shell prompt unambiguously. This method is called automatically by the `login()` method, but you may want to call it manually if you somehow reset the shell prompt. For example, if you ‘su’ to a different user then you will need to manually reset the prompt. This sends shell commands to the remote host to set the prompt, so this assumes the remote host is ready to receive commands.

    Alternatively, you may use your own prompt pattern. In this case you should call `login()` with `auto_prompt_reset=False`; then set the `PROMPT` attribute to a regular expression. After that, the `prompt()` method will try to match your prompt pattern.