`relation-set`¶

Summary¶

Sets relation settings.

Usage¶

relation-set [options] key=value [key=value ...]

Options¶

Flag	Default	Usage
`--app`	false	Sets relation settings for the application instead of the unit (leader only).
`--file`		Specifies a file containing key-value pairs.
`--format`		(DEPRECATED) Format flag.
`-r`, `--relation`		Specifies a relation by ID.

Examples¶

relation-set port=80 tuning=default

relation-set -r server:3 username=jim password=12345

Details¶

relation-set writes the local unit’s settings for some relation.

If no relation is specified then the current relation is used. If it’s not running in a relation hook, -r needs to be specified.

The setting values are not inspected and are stored as strings. Setting an empty string causes the setting to be removed. Duplicate settings are not allowed.

If the unit is the leader, it can set the application settings using --app. These are visible to related applications via relation-get --app or by supplying the application name to relation-get in place of a unit name.

The --file option should be used when one or more key-value pairs are too long to fit within the command length limit of the shell or operating system. The file will contain a YAML map containing the settings. Settings in the file will be overridden by any duplicate key-value arguments. A value of "-" for the filename means <stdin>.

relation-set is the tool for communicating information between units of related applications. By convention the charm that provides an interface is likely to set values, and a charm that requires that interface will read values; but there is nothing enforcing this. Whatever information you need to propagate for the remote charm to work must be propagated via relation-set, with the single exception of the private-address key, which is always set before the unit joins.

For some charms you may wish to overwrite the private-address setting, for example if you’re writing a charm that serves as a proxy for some external application. It is rarely a good idea to remove that key though, as most charms expect that value to exist unconditionally and may fail if it is not present.

All values are set in a transaction at the point when the hook terminates successfully (i.e. the hook exit code is 0). At that point all changed values will be communicated to the rest of the system, causing -changed hooks to run in all related units.

There is no way to write settings for any unit other than the local unit. However, any hook on the local unit can write settings for any relation which the local unit is participating in.

relation-set¶