The Configuration File

Exosphere loads all of its settings and inventory from a configuration file. The configuration file can be provided in multiple formats, including yaml, toml, and json.

Location

Where the configuration file lives will depend on your platform. For instance, for a YAML configuration file, the default locations are:

~/.config/exosphere/config.yaml

You can of course substitute the file extension with .toml or .json if you wish to use those formats instead.

You can also ask Exosphere where it expects the configuration file to be on your platform:

exosphere config paths

Additionally, you can specify a custom configuration file location via the EXOSPHERE_CONFIG_FILE environment variable, with the full path to the file as the value.

Structure

The configuration file is split into two main sections, Options and Hosts. The Options section contains general settings for Exosphere, while the Hosts section contains the Inventory of hosts that Exosphere will connect to.

Below is a full example of a configuration file, in all supported formats. Any option left out will use the default values, which are documented below.

options:
  log_level: DEBUG
  max_threads: 5  # Limit parallel actions to 5 threads
  default_username: alice  # Default username across hosts (optional)
hosts:
  - name: host1
    ip: host1.example.com
  - name: host2
    ip: host2.example.com
    port: 2222
    description: "Example Host"
  - name: host3
    ip: host3.example.com
    description: "Another Example Host"
    username: admin  # Override username for this host
    sudo_policy: nopasswd

Environment Variables

The location of the configuration file can be overridden by setting the EXOSPHERE_CONFIG_FILE environment variable to the full path of the file you wish to use.

export EXOSPHERE_CONFIG_FILE="/path/to/my/config.yaml"

Tip

There is also EXOSPHERE_CONFIG_PATH, which you can use to specify a directory where a config file named config.{yaml,yml,toml,json} will be searched for. This can be useful in certain deployments.

Exosphere also supports loading configuration options from environment variables. You can use this to override any specific Option from the configuration file. You cannot use environment variables to override the Hosts section.

The environment variable names are prefixed with EXOSPHERE_OPTIONS_ and the option name in uppercase.

For example, to override the log_level option, set the following environment variable:

export EXOSPHERE_OPTIONS_LOG_LEVEL="DEBUG"

This pattern applies to all configuration options.

Note

Option types are all strings in this context, but they will be parsed as json types when loaded. This means “true” and “false” will correctly be interpreted as booleans, and “null” will be interpreted as None. Essentially, you do not need to worry about it as type conversion is properly handled automatically.

Exosphere can display which environment variables are influencing the configuration (if any):

exosphere config source

Options

The options section contains general settings for Exosphere. These options are applied globally, and affect how Exosphere behaves at runtime.

Below is a detailed list of all available options, their defaults, and examples of how to set them in the configuration file.

log_level

The logging level for Exosphere. This can be set to one of the following values, as a string:

  • DEBUG

  • INFO

  • WARNING

  • ERROR

This controls the verbosity of the logs generated by Exosphere.

Default: INFO

Example:

options:
  log_level: DEBUG
default_sudo_policy

The global sudo policy to use when running commands on hosts. This can be set to one of the following values:

  • skip: Do not run commands that require sudo at all

  • nopasswd: Assume sudoers configuration allows running the provider commands without a password

This controls how Exosphere will handle sudo permissions when running commands on hosts. The default is skip, which means Exosphere will not attempt to use sudo at all.

If you want Exosphere to run commands that require elevated privileges at all, you must configure your sudoers file to allow the user Exosphere connects as to run those commands with NOPASSWD: in the sudoers file.

More details on how to configure this can be found in the Connections and Privileges documentation.

Note

Depending your used Providers, you may not need to configure this at all! See the Providers documentation for more details.

This is the global value that, by default, applies to all hosts. It can be overridden on a per-host basis in the inventory, inside the hosts section, via sudo_policy.

Default: skip

Example:

options:
  default_sudo_policy: nopasswd
debug

Enable debug mode, which sets the root logger to DEBUG level. This is useful for development and debugging purposes, if you also want to see debug logs from libraries and other components.

Normally, there’s very little reason to enable this unless you are actively developing Exosphere or troubleshooting a specific issue.

Caution

Enabling debug mode will absolutely flood your logs with debug messages from both Exosphere and all of its dependencies. We do not recommend enabling this unless you know what you are doing.

You probably want to set log_level to DEBUG instead.

Default: false

Example:

options:
  debug: true
log_file

A filesystem path to a file where Exosphere will write logs. If not set, Exosphere will use the platform default location for application logs.

You can set this to any valid path on your filesystem where you have write permissions.

Default: (Platform Default)

Example:

options:
  log_file: /home/alice/tmp/exosphere.log
history_file

A filesystem path to a file where Exosphere will store the REPL history. If not set, Exosphere will use the platform default and name the file repl_history.

This file is used to persist the command history across executions of Exosphere, allowing you navigate through or search for previously executed commands.

Default: (Platform Default)

Example:

options:
  history_file: /home/alice/.exosphere_history
cache_autosave

Automatically save the state to disk when changes are made. This is on by default, and probably should not be turned off unless you have a very specific reason to do so.

If this is disabled, you will need to manually save the state with inventory save from the interactive mode for changes to systems state to persist across executions.

See Managing Cache for more details on the cache file

Caution

Note that a manual save can only be done in interactive mode. Running Exosphere in non-interactive mode with this option disabled will not save the state at all between executions.

Default: true

Example:

options:
  cache_autosave: false
cache_autopurge

Whether or not to automatically remove hosts from cache when they are removed from the configuration file.

If cache_autosave is set to False, this option has no effect.

Note

If all of the hosts are removed from the configuration file, Exosphere will err on the side of caution and leave the cache file alone, regardless of this setting.

This is to prevent accidental cache loss if the wrong configuration is loaded, or if the file is made temporarily inaccessible.

If you really want to remove all the contents of the cache file, use the exosphere inventory clear command.

Default: true

Example:

options:
  cache_autopurge: false
cache_file

A filesystem path to a file where Exosphere will store the state of the inventory. If not set, Exosphere will use the platform default location for the cache file.

This file is used to persist the state of the inventory across executions, including the results of discovery, host updates, last check times, and more.

The file is lzma compressed to save space, and is not human readable.

It can be cleared with the exosphere inventory clear command, without having to delete the file manually.

See Managing Cache for more details on the cache file

Default: (Platform Default)

Example:

options:
  cache_file: /home/alice/tmp/exosphere.db
stale_threshold

The number of seconds after which a host data is considered stale.

If a host has not been refreshed in this many seconds, an asterisk or similar flag will be shown in the UIs to indicated that the update count may not be accurate, and that the host should be refreshed.

The default is 24 hours, which is reasonable, but you may want a shorter or longer span of time depending on your environment.

Default: 86400 (24 hours)

Example:

options:
  stale_threshold: 3600  # 1 hour
default_timeout

The number of seconds to wait for a response from a host over SSH.

This is the maximum time Exosphere will wait for a response from a host before timing out, flagging the host as offline, or raising an error condition.

This is useful for hosts that may be slow to respond, or if you have a large number of hosts and want to avoid long delays on That One Host.

Note

This is the global value that, by default, applies to all hosts. It can be overridden on a per-host basis in the inventory, inside the hosts section, via connect_timeout.

Default: 10 (seconds)

Example:

options:
  default_timeout: 60  # 1 minute
default_username

The default SSH username to use when connecting to hosts. This is useful if you have a common username across all hosts, and do not want to specify it for each host in the inventory.

If not set, Exosphere will try to use the current user’s username on the system where Exosphere is running.

Note

This is the global value that, by default, applies to all hosts. It can be overridden on a per-host basis in the inventory, inside the hosts section, via username.

Default: None (Current user’s username)

Example:

options:
  default_username: alice  # Use 'alice' as the default SSH username
max_threads

The maximum number of threads to use for parallel operations.

This is the maximum number of threads Exosphere will use for parallel operations, such as discovery, ping, checking for updates or synchronizing repositories.

This can be useful to limit the number of concurrent operations, especially in environments with many hosts, to avoid overwhelming the network or the computer where you are running Exosphere.

The default is a generous 15 threads, which you may want to lower depending on your context.

Default: 15

Example:

options:
  max_threads: 5  # Limit parallel actions to 5 threads
ssh_pipelining

Enable SSH connection pipelining to improve performance when connecting to multiple hosts.

By default, Exosphere closes connections automatically after each Host operation (sync, discover, refresh, ping etc).

Enabling this option will leave connections open for reuse across multiple operations, significantly improving performance in workflows that involve multiple operations on the same hosts.

Idle connections will be closed automatically after a certain period of time, configurable via ssh_pipelining_lifetime, and reaped periodically via ssh_pipelining_reap_interval.

Default: false

Example:

options:
  ssh_pipelining: true
ssh_pipelining_lifetime

The number of seconds an idle SSH connection will be kept open when SSH pipelining is enabled.

This setting only applies if ssh_pipelining is set to true.

When a connection has been idle (unused) for longer than this duration, it will be closed by the connection reaper thread.

Attention

Setting this value too low may negate the performance benefits of SSH pipelining, as connections will be closed before they can be reused.

You will get a warning in the logs to this effect if you configure this value to be less than 60 seconds. Consider setting this to at least the longest time an operation may take on your slowest host, as a baseline.

Otherwise, you can leave this at the default value.

Default: 300 (5 minutes)

Example:

options:
  ssh_pipelining_lifetime: 240  # 4 minutes
ssh_pipelining_reap_interval

The interval (in seconds) at which the reaper thread wakes up to check for and close idle SSH connections when SSH pipelining is enabled.

This setting only applies if ssh_pipelining is set to true.

Attention

Setting this value too high will cause idle connections to remain open for longer than necessary, potentially extending their lifetime beyond ssh_pipelining_lifetime by up to this interval duration.

Conversely, having the reaper thread wake up frequently has negligible overhead since it will only perform work when there are actually idle connections to close.

You should consider that this value effectively adds up to this amount of time to the actual lifetime of idle connections. For example, with a lifetime of 300s and an interval of 30s, connections may remain open for up to 330s.

If in doubt, leave this at the default value.

Default: 30 (30 seconds)

Example:

options:
  ssh_pipelining_reap_interval: 60  # 1 minute
update_checks

Whether or not Exosphere is allowed to check for updates on PyPI.

Exosphere currently doesn’t perform any automatic update checks, only when explicitly asked to via the version check command.

This option allows you to disable that functionality entirely.

This is intended for:

  • Environments that have stringent policies about external connectivity

  • Environments where Exosphere is installed by other means than PyPI

  • Brave souls who would package Exosphere in the context of an OS distribution.

In all of these contexts, the version check command will be disabled and print a clear message instead.

If in doubt, leave this at the default value.

Default: true

Example:

options:
  update_checks: false
no_banner

Do not show the ascii banner when starting Exosphere in interactive mode. Setting this to true will suppress the banner entirely, showing only the welcome text and the prompt.

Tip

This can be be set contextually with the environment variable EXOSPHERE_OPTIONS_NO_BANNER set to true. For more details see Environment Variables.

Default: false

Example:

options:
  no_banner: true

Inventory

The second section of the configuration file is the Hosts section, which is referred throughout the documentation as The Inventory.

The Hosts section contains a list of hosts that Exosphere will connect to, as well as their connection parameters and any specific option for each host.

Host entries are structured as follows. This example describes two hosts, one of which has a custom connection timeout value set, overriding default_timeout.

hosts:
  - name: myhost
    ip: myhost.example.com
  - name: anotherhost
    ip: 127.0.1.8
    connect_timeout: 30

Mandatory fields for each host entry are:

  • name: The name of the host, which is used to identify it in the UI and logs.

  • ip: The address of the host, which can be a hostname or an IP address.

Optional fields for each host entry include:

  • port: The SSH port to connect to the host. Defaults to 22.

  • username: An optional SSH username to use when connecting to the host

  • description: A short string describing the host, to be displayed in UIs

  • connect_timeout: The number of seconds to wait for a response from the host over SSH

  • sudo_policy: The sudo policy to use when running commands on the host

Below is the detailed list of all available host options and their defaults.

name

The name of the host, which uniquely identifies the host within the inventory. It is recommended to keep this to a short string rather than a fully qualified domain name, although it can be arbitrary.

Attention

The name field has a unicity constraint within the inventory! You cannot have two hosts with the same name value, and Exosphere will inform you of this if it is the case, before promptly refusing to load the configuration file.

Mandatory: Yes

Example:

hosts:
  - name: myhost
ip

The IP address or hostname of the host to connect to over SSH. This can be a fully qualified domain name, an IP address, or a short hostname, so long as it resolves. It is recommended to use a fully qualified domain name or an IP address to avoid issues with DNS resolution.

Attention

The ip field must not contain the @ character. To specify a username, use the username field instead.

Mandatory: Yes

Example:

hosts:
  - name: myhost
    ip: myhost.example.com
port

The SSH port to connect to the host. This is optional, and defaults to 22. If your host uses a different port for SSH, you can specify it here.

Default: 22

Example:

hosts:
  - name: myhost
    ip: myhost.example.com
    port: 2222
username

An optional SSH username to use when connecting to the host.

Note

This option has precedence over default_username

This is useful if you need to connect to a particular host with a different user than the one you are running Exosphere as, or the one configured globally in default_username.

Default: Current user’s username

Example:

hosts:
  - name: myhost
    ip: myhost.example.com
    username: alice
description

A short string describing the host, to be displayed in UIs. This is optional, but can be useful to provide additional context about the host, such as its role or purpose.

Default: None

Example:

hosts:
  - name: myhost
    ip: myhost.example.com
    description: "Web Server"
connect_timeout

The number of seconds to wait for a response from the host over SSH. This is optional, and defaults to the value set in default_timeout.

If you have hosts that are particularly slow to respond, you can increase this value on a per-host basis.

Default: Value of default_timeout

Example:

hosts:
  - name: myhost
    ip: myhost.example.com
    connect_timeout: 30  # 30 seconds
sudo_policy

The sudo policy to use when running commands on the host.

Note

This option has precedence over the global option, see default_sudo_policy for documentation and usage details.

Default: Value of default_sudo_policy

Example:

hosts:
  - name: myhost
    ip: myhost.example.com
    sudo_policy: nopasswd