API¶

Configuration Objects¶

class fox.conf.Environment¶

Fox is configured through the global variable env which is an instance of Environment.

host_string = None¶: The hostname of the remote server that will be used in all of the run(), sudo() and all of the other remote commands.

port = None¶: The remote port.

private_key = None¶: The path to a OpenSSH private key.

ssh_config_path = '/home/docs/.ssh/config'¶: Set the path to the OpenSSH configuration file.

sudo_password = None¶: Set the password for the sudo() commands.

sudo_prompt = 'sudo password:'¶: The prompt for sudo commands (do not change!).

term_size = (80, 24)¶: The size of the emulated terminal when a pty is requested.

term_type = 'vt100'¶: The terminal type to emulate when a pty is requested.

use_ssh_config = True¶: Set to True to enable the loading of ~/.ssh/config.

username = None¶: The remote username.

fox.conf.env = <fox.conf.Environment object>¶: Global configuration object.

API Methods¶

fox.api.run(command, pty=False, cd=None, environ=None, echo=True) → fox.utils.CommandResult¶

Run a command on the current env.host_string remote host.

Parameters:	command – the command line string to execute. pty – wether to request a remote pty. cd – the optional name of the directory where the command will be executed. environ – an optional dictionary containing environment variables to set when

executing the command. :param echo: set to False to hide the output of the command.

fox.api.run_concurrent(hosts, command, limit=0)¶

Execute command on hosts concurrently.

Parameters:	hosts – a list of hosts where to run command. command – the command line string to execute. limit – limit the concurrent execution to limit hosts; set to 0 to execute on all the

hosts at once.

fox.api.sudo(command, pty=False, cd=None, environ=None, echo=True) → fox.utils.CommandResult¶

Run a command on the current env.host_string remote host with sudo

Parameters:	command – the command line string to execute. pty – wether to request a remote pty. cd – the optional name of the directory where the command will be executed. environ – an optional dictionary containing environment variables to set when

executing the command. :param echo: set to False to hide the output of the command.

fox.api.get(remotefile, localfile)¶

Download a file from the remote server.

Parameters:	remotefile – the path to the remote file to download. localfile – the local path where to write the downloaded file.

fox.api.put(localfile, remotefile)¶

Upload a local file to a remote server.

Parameters:	localfile – the path of the local file to upload. remotefile – the path where to write the file on the remote server.

fox.api.read(remotefile) → bytes¶

Read the contents of a remote file.

Parameters:	remotefile – the path of the remote file to read.

This is useful when you just want to read the contents of a remote file without downloading it.

fox.api.file_exists(remotefile) → bool¶

Check if a file exists on the remote server.

Parameters:	remotefile – the path of the remote file that will be checked.

fox.api.local(command, cd=None, environ=None, env_inherit=True) → fox.utils.CommandResult¶

Execute command on the local machine.

Parameters:	command – the command line string to execute. cd – the optional name of the directory where the command will be executed. environ – an optional dictionary containing environment variables to set when

executing the command. :param env_inherit: set to False when you also specify env to execute the process in a new blank environment.

Connection Object¶

class fox.connection.Connection(hostname: str, username: str, port: int, private_key=None, password: Optional[str] = None, agent_path: Optional[str] = None, tunnel: Optional[str] = None, nickname: Optional[str] = None)¶

A SSH connection to a remote server.

Parameters:

hostname – hostname of the remote server.
username – the username used to log into the remote server.
port – the optional port for connecting to the remote server (default: 22).
private_key – the optional path to a OpenSSH private key.
password – the optional password used to authenticate to the remote server.
agent_path – the optional path to a OpenSSH agent socket.
tunnel – the optional hostname of another server that will be used as tunnel.
nickname – the hostname of the server as passed on the command line (could be different from the real hostname configured in ~/.ssh/config).

disconnect()¶: Close the SSH connection to the server.

file_exists(remotefile) → bool¶

Check if a file exists on the remote server.

Parameters:	remotefile – the path of the remote file that will be checked.

get(remotefile, localfile)¶

Download a file from the remote server.

Parameters:	remotefile – the path to the remote file to download. localfile – the local path where to write the downloaded file.

put(localfile, remotefile)¶

Upload a local file to a remote server.

Parameters:	localfile – the path of the local file to upload. remotefile – the path where to write the file on the remote server.

read(remotefile) → bytes¶

Read the contents of a remote file.

Parameters:	remotefile – the path of the remote file to read.

This is useful when you just want to read the contents of a remote file without downloading it.

run(command, pty=True, cd=None, environ=None, echo=True) → fox.utils.CommandResult¶

Execute a command on the remote server.

Parameters:	command – the command line string to execute. pty – wether to request a remote pty. cd – the optional name of the directory where the command will be executed. environ – an optional dictionary containing environment variables to set when executing the command. echo – set to False to hide the output of the command.

sudo(command, pty=True, cd=None, environ=None, echo=True) → fox.utils.CommandResult¶

Execute a command with sudo on the remote server.

Parameters:	command – the command line string to execute. pty – wether to request a remote pty. cd – the optional name of the directory where the command will be executed. environ – an optional dictionary containing environment variables to set when executing the command. echo – set to False to hide the output of the command.

Cluster Object¶

class fox.cluster.Cluster(*hosts)¶

Cluster mode.

Run a command on several hosts in parallel.

TOOD: - canary run (do a canary run on the first host before doing the remanining) - exit after % of hosts failed

fox.cluster.connect_pipes(source, source_command, destination, destination_command)¶

Connects processes on two connections with a pipe

Pipe stdout and stderr from a command executed on a source connection to stdin of a process on a destination connection.

SSHConfig Object¶

class fox.sshconfig.SSHConfig¶

Parse a OpenSSH configuration file and lookup SSH options for connecting to a given host.

load(filename: str)¶: Load and parse a OpenSSH configuration file.

lookup(nickname: str) → Dict[str, Any]¶: Lookup SSH options for connecting to the server nickname.

exception fox.sshconfig.Error¶: An error encountered while parsing a OpenSSH configuration file

CommandResult Object¶

CommandResult objects are returned by all the fox.api.run(), fox.api.sudo(), fox.api.local() functions and their corresponding methods in the fox.connection.Connection class and can be used to inspect the results of the execution of a command.

class fox.utils.CommandResult(command: str, actual_command: str, exit_code: int, stdout: str, stderr: str, hostname: str, sudo: bool = False)¶

Use the CommandResult.stdout and CommandResult.stderr attributes to inspect stdout and stderr of the process.

actual_command = None¶: The actual command that was executed, including all the cd and env prefixes.

command = None¶: The command that was executed.

exit_code = None¶: The exit code of the executed command.

hostname = None¶: The hostname of the server where the command was executed.

stderr = None¶: The (partial) stderr output of the executed command.

stdout = None¶: The (partial) stdout output of the executed command.

sudo = False¶: Wether the command was executed with sudo.