Document what attributes control what in one place

[bsanders]

There are a number of attributes that have meaning at different levels (for example, kickstartable, managed, etc). These should be documented in one place with a description of what they control and when they should be set.

[bsanders]

A (full?) list of attributes that should be documented:

firewall                       -------- true
kickstartable                  -------- true
managed                        -------- true
node                           -------- backend
nukedisks                      -------- False
ssh.use_dns                    -------- true
sync.ssh.authkey               -------- true
time.protocol                  -------- chrony

[bsanders]

See also:

authorized_keys
boot_device
nukecontroller
secureerase

[bsanders]

Here's a start:

kickstartable -- hosts with kickstartable == True will be offered a kickstart file, and more specifically their entry in dhcpd.conf will have PXE settings enabled. This defaults to True.

managed -- hosts with managed == True will have stack run host commands run against them. They will also be the target of several stack sync commands. Defaults to False for Frontends, True for all other appliances.

node -- the node attribute dictates which xml file in the graph to use as the starting point. The default setting for this attribute is typically inherited from the appliance. The backend appliance defaults to backend.

nukedisks -- hosts with nukedisks == True will have all partitions on all disks wiped as part of their next install. This defaults to False and is automatically set back to False at the end of the install.

nukecontroller -- hosts with nukecontroller == True will have their internal storage controller disk layout erased as part of their next install. This defaults to False and is automatically set back to False at the end of the install.

secureerase -- hosts with secureerase == True will have their disks cryptographically erased (where hardware-supported) as part of their next install. This implies nukecontroller == True and nukedisks == True. This defaults to False and is automatically set back to False at the end of the install. Stacki > 5.0

ssh.use_dns -- hosts with ssh.use_dns == True will enable DNS lookups in sshd config. This defaults to True.

boot_device -- hosts with boot_device set will have their bootloader installed to the boot sector of the device referred to (eg. 'sdb')

authorized_keys -- authorized_keys may be set to a single public key, or a (http/https/ftp/file) URL containing one or more keys, in the format of the ~/.ssh/authorized_keys file. Regardless, the contents will be populated in /root/.ssh/authorized_keys on the the host. Any URL specified must be available to the frontend if pxebooting, or the installing node if booting from dvd/flash. Stacki > 5.0

firewall -- firewall controls whether or not Stacki will keep the firewall on a given host in sync after the initial install. This defaults to True.

sync.ssh.authkey -- hosts with sync.ssh.authkey == True will have a copy of the frontend's public key placed in their /root/.ssh/authorized_keys file. This defaults to True.

time.protocol -- time.protocol must be set to either ntp or chrony. Installed nodes will be configured to run the specified time service. Either time service will be configured to point to time.server, if it is defined, or Kickstart_PublicNTPHost in the case of frontends, and Kickstart_PrivateNTPHost in the case of other hosts.

time.server -- time.server is the server what the time service will attempt to contact, overriding the Kickstart_PrivateNTPHost and Kickstart_PublicNTPHost attributes.

disklabel -- disklabel controls whether Stacki will create GPT or MSDOS-based partitions. The input is passed to parted's mklabel command, but has only been tested with gpt and msdos. This defaults to gpt.

run.host.impl -- this controls the method for running commands against hosts when using stack run host. Currently the default and only supported implementation is ssh.

run.host.threads -- the number of threads/processes to concurrently run commands against hosts.

[masonkatz]

Create a new table

attr	doc

Where attr is the name of the attribute and doc is the doc text for usage. The doc text is set from the add attr commands (add a doc=) flag. This way users can document their own attributes and by keeping this in another table we avoid the scoping stuff and treat all attributes as reserved words (meanings they have the same semantics at all scopes).

[bsanders]

Since it's a DB change, I'm suggesting this goes into 5.0

[bsanders]

The database table and relevant commands for interacting with it went into 8070e1d. The actual default documentation strings (which should probably land in a node XML file?) did not land yet. See above for a start, but it is still TODO.

[bsanders]

The branch feature/add_attr_docs has been created to add the actual documentation via the command added in the previous comment. If anyone has any thoughts on the text of the above, see #432.