Rosters#

Rosters is the system that is used to define the target systems to create connections to with Heist. The default roster system is called flat and uses the POP rend system to render the datasets.

Note

By using the flat roster you can make roster files using yaml, json, toml etc. and template the files making it easy to allow for logic to make larger lists easier. Don’t worry! You don’t need to know anything about rend to use rosters. Just know that there is a robust system under the hood to make your life easier!

Defining a basic roster is easy:

192.168.0.24:
  username: harry
  password: foobar

In this roster we are using the default yaml rend system. It is also very simple because it is just a password login. Heist supports logging into systems using virtually any login mechanism available to SSH. The options are mapped directly to asyncssh and can be found here: https://asyncssh.readthedocs.io/en/latest/api.html#asyncssh.SSHClientConnectionOptions

You can change the rend system used to render the rosters by setting the renderer option. By default this is set to yaml.

Common Roster Options#

Use password authentication:

192.168.0.24:
  username: harry
  password: foobar

Using an SSH key for authentication:

192.168.0.24:
  username: harry
  client_keys:
    - /path/to/ssh/key

Using an SSH key with a passphrase for authentication:

192.168.0.24:
  username: harry
  client_keys:
    - /path/to/ssh/key
  passphrase: "password"

Using sudo:

192.168.0.24:
  username: harry
  password: foobar
  sudo: True

Using sudo with a tty. You need to set tty to True if you are using sudo and a password. Heist will interactively input the password defined in the roster when sudo asks for a password. If you have NOPASSWD set in /etc/sudoers for the defined user you do not need to set tty to True unless requiretty is set on your target. Here is an example:

192.168.0.24:
  username: harry
  password: foobar
  sudo: True
  tty: True

Using sudo with a tty while defining the term_type and term_size. The term_type and term_size are defining AsyncSSH’s term_type and term_size options. The term_type defines the terminal type to use for the session. By default this is xterm-color. The term_size defines the terminal width and height in characters. By default term_size is set to (80,24). Here is an example of setting both term_type and term_size:

192.168.0.24:
  username: harry
  password: foobar
  sudo: True
  tty: True
  term_type: xterm
  term_size: (80, 24)

Roster Defaults#

If you need to set roster options to be used for all hosts you are targeting you can set roster_defaults in the heist configuration file. The heist configuration file by default is at /etc/heist/heist.conf.

{"roster_defaults":
  {"username": "root"}}

List of Available Rosters#

roster modules

Roster Data#

Heist allows you to pass in roster data without using a pre-definied roster file. The config roster-data allows a user to pass in json data to be used for the roster data.

heist salt.minion --roster-data='{"test1":{"host":"192.168.1.2","username":"root","password":"hostpasswd"}}'

The above command will use the host, username and password defined in the json data passed in with –roster-data. If you also use roster-file alongside –roster-data, heist will write the roster data to the specified roster file. For example:

heist salt.minion --roster-data='{"test1":{"host":"192.168.1.2","username":"root","password":"hostpasswd"}}' --roster-file=/tmp/heist-roster

This will write the data from –roster-data to the file /tmp/heist-roster.