JarCastingDescription
Clavin is a basic command-line tool for dealing with configuration files at iPlant. Its primary purposes are to:
-
load ACLs into Zookeeper;
-
load configuration settings into Zookeeper;
-
generate configuration files from templates.
Overview
On an admin machine (admin machines are described below):
clavin hosts --host 127.0.0.1 --acl myacls.properties
clavin props --host 127.0.0.1 --acl myacls.properties -f myenvironments.clj -t
/path/to/template-dir -a app -e env -d deployment
On a machine where WAR files are being deployed:
clavin files -f myenvironments.clj -t /path/to/template-dir -a app -e env -d
deployment --dest /path/to/dest-dir
To list current configuration settings on a services host:
clavin get-props --host 127.0.0.1 -s service-name prop-name-1 prop-name-2
To list current configuration settings on another host:
clavin get-props --host 127.0.0.1 --service-host somehost -s service-name prop-name-1 prop-name-2
Environment listing and validation:
clavin envs -l -f myenvironments.clj
clavin envs -v -f myenvironments.clj
Getting help:
clavin help
clavin envs -h
clavin files -h
clavin hosts -h
clavin props -h
Specifying Zookeeper Connection Settings
Zookeeper connection settings can be specified in one of two ways: either by specifying the host and port directly on the command line or by reading the file that the services use to obtain the connection settings, zkhosts.properties. In the former case, the options to use are --host and --port. The --port setting defaults to 31381 if it's not specified. The --host option defaults to nil, meaning that Clavin will look for zkhosts.properties. For a concrete example, suppose you wanted to list the properties for the service, foo, on the Zookeeper process running on the local host and listening on the standard port. The following command could be used for that:
$ clavin get-props --host localhost -s foo
Now suppose that Zookeeper is listening on port 2001 instead. In that case, the equivalent command would look something like this:
$ clavin get-props --host localhost --port 2001 -s foo
If you have a copy of zkhosts.properties in a specific location on the local machine then you can tell Clavin to obtain the connection settings from that file using the -z or --zkhosts-path command-line option. If you wanted to use the copy of zkhosts.properties in your home directory, for example, then the equivalent command from the example above would be something like this:
$ clavin get-props -z ~/zkhosts.properties -s foo
Finally, if your copy of zkhosts.properties is located in the default location (/etc/iplant-services/zkhosts.properties), then you can leave the connection settings off of the command line completely:
$ clavin get-props -s foo
Note that these options apply to all sub-commands that interact with Zookeeper, but the examples below will all specify --host directly.
Creating an ACLs file
An "ACL file" is simply a java properties file that lists the ip-addresses of machines that are in a particular environment (dev, qa, stage, prod, etc.). Each environment can have multiple deployments. For instance, dev has dep-1 and dep-2. Here's the ACLs file for the dep-1 deployment (you can list multiple deployments in one file).
app.dev.dep-1 = 192.168.1.1,\
192.168.1.2,\
192.168.1.3,\
192.168.1.4,\
192.168.1.5
admin = 192.168.1.5,\
192.168.1.6,\
192.168.1.7
The naming of the keys is significant. Any machine listed in the "admin" value will be given admin privileges in Zookeeper for the deployments included in the ACLs file.
The "app.dev.dep-1" key tells clavin the application name, environment, and deployment that is being described. In this case, "app" is the application name, "dev" is the environment, and "dep-1" is the deployment. These values correspond with the --app (-a), --env (-e), and --deployment (-d) options that clavin uses when setting properties in Zookeeper. More on that below.
The values associated with each key in the ACLs file are comma separated lists of IP addresses.
High level guidelines for organizing ACL files
-
Don't reuse the same IP address in multiple deployments.
-
If an IP address appears in a deployment and as an admin machine, then that deployment and admin section should be in the same ACL file.
-
If an IP address appears in multiple admin sections in different files, then consider merging those files.
Loading ACLs file into Zookeeper
Once you've got the ACLs file put together, you load it into Zookeeper with the following command:
clavin hosts --host 127.0.0.1 --acl <path-to-acls-file>
That will create entries in /hosts on Zookeeper for each machine and tell what deployments it's associated with (deployments are analogous to groups in this case).
For instance, since 192.168.1.5 is listed both as an admin machine and as a machine in the "app.dev.dep-2" deployment, Zookeeper will create the following nodes for it:
[zk: localhost:31381(CONNECTED) 2] ls /hosts/192.168.1.5
[app.dev.dep-2, admin]
In other words, the /hosts/192.168.1.5/app.dev.dep-2 and /hosts/192.168.1.5/admin nodes both exist. The ACLs on the "admin" node are as follows:
[zk: localhost:31381(CONNECTED) 4] getAcl /hosts/192.168.1.5/admin
'ip,'192.168.1.5
: cdrwa
'ip,'192.168.1.6
: cdrwa
'ip,'192.168.1.7
: cdrwa
'ip,'192.168.1.5
: rw
Translation: Every admin node is listed as having admin access (the "cdrwa" part) and the node itself has read-write access. This means that other machines can't accidentally or maliciously nuke the group/deployment memberships unless they are listed as an admin node in the ACLs file.
Creating Configuration File Templates
Clavin uses configuration file templates in conjunction with deployment-specific configuration setting definitions in order to generate configuration settings. Once the configuration settings have been generated, they may either be loaded directly into Zookeeper or written to a file for inspection or use by a web application.
The configuration file templates used by Clavin consist of plain text with configuration placeholders interspersed throughout the text. The placeholders consist of property names surrounded by dollar signs. For example:
foo.bar.baz = $some_property$
The property names should be valid java identifiers. (That is, they should begin with either an underscore or an alpha character and be followed by zero or more underscores or alphanumeric characters.) The preferred naming convention is to separate words in identifiers with underscores rather than to use camelCase. The reason for this has to do with the definition of the placeholder values, which will be described in the Creating an Environments File section.
Literal dollar signs can be included the file by preceding the dollar sign with a backslash:
dr.evil.catch-phrase = ...unless you bring me \$1,000,000!
Each service has its own configuration file template, with the template file named after the service with a extension of .st. For example, the service, donkey, would have a template file named donkey.st. (The .st file name extension stands for "String Template", which is the library used to process the template files.) Here's an example configuration file template, nibblonian.st:
# Jargon-related configuration
nibblonian.irods.host = $irods_host$
nibblonian.irods.port = $irods_port$
nibblonian.irods.user = $irods_user$
nibblonian.irods.password = $irods_password$
nibblonian.irods.home = $irods_home$/
nibblonian.irods.zone = $irods_zone$
nibblonian.irods.defaultResource = $irods_default_resource$
# Application-specific configuration
# Controls the size of the preview. In bytes.
nibblonian.app.preview-size = 8000
# The size (in bytes) at which a preview becomes a rawcontent link in the
# manifest.
nibblonian.app.data-threshold = 8000
# The maximum number of attempts that nibblonian will make to connect if the
# connection gets severed.
nibblonian.app.max-retries = 10
# The amount of time (in milliseconds) that the nibblonian will wait between
# connection attempts.
nibblonian.app.retry-sleep = 1000
# Set this value to 'true' to send deleted files and folders to the Trash.
nibblonian.app.use-trash = true
# A comma delimited list of file/directory names that should be filtered from
# Nibblonian listings.
nibblonian.app.filter-files = cacheServiceTempDir
# The path to the community data directory in iRODS
nibblonian.app.community-data = $irods_home$/shared
#The port nibblonian should listen on
nibblonian.app.listen-port = $nibblonian_port$
#REPL-related configuration
nibblonian.swank.enabled =
nibblonian.swank.port =
If the name of the template has a file extension prior to the .st , eg. name.ext.st, the name of the generated configuration file will be just the template name, eg. name.ext. Otherwise, the name of the generated file will be the template name with .properties extension added.
Listing and Validating Configuration File Templates
When generating configuration settings, it can be useful to list the available templates. Also, when a template file is modified or created, it can be useful to verify that it is formatted correctly before attempting to generate configuration settings from it. Clavin provides the templates subcommand for these settings:
clavin templates -t <path-to-template-dir> [-l|-v]
Here's an example template file listing:
$ clavin templates -l -t ~/tmp/templates/
belphegor-confluence
belphegor
buggalo
confluence
conrad
discoveryenvironment
donkey
iplant-email
jex
metadactyl
nibblonian
notificationagent
osm
panopticon
scruffian
Here's an example successful template file validation:
$ clavin templates -v -t ~/tmp/templates/
All templates are valid.
Here's an example unsuccessful template file validation:
$ clavin templates -v -t ~/tmp/templates/
belphegor-confluence is invalid: #<STLexerMessage 4:77: invalid character '-'>
belphegor-confluence is invalid: #<STCompiletimeMessage 4:78: 'base' came as a complete surprise to me>
Errors were found.
Validating Templates Against an Environments File
Clavin also provides the ability to validate templates against an environments file to verify that there are no undefined properties referenced in the templates and no unused properties defined in the environments file. To do this, simply validate the templates and include the path to the environments file.
Here's an example unsuccessful validation:
$ clavin templates -t ~/tmp/templates -f environments.clj -v
Unused parameters were detected in dev.de-1:
:db-max-idle-minutes
Unused parameters were detected in dev.de-2:
:db-max-idle-minutes
Unused parameters were detected in qa.penguin:
:db-max-idle-minutes
Unused parameters were detected in qa.qa-1:
:db-max-idle-minutes
Unused parameters were detected in qa.qadb:
:db-max-idle-minutes
Unused parameters were detected in prod.prod:
:db-max-idle-minutes
Unused parameters were detected in staging.staging:
:db-max-idle-minutes
Errors were found.
Creating an Environments File
The environments file defines the deployment-specific settings that are plugged into the templates in order to generate the full-blown configuration settings. This file is just a plain Clojure source file containing a single nested map definition:
{:first-setting
{[:env-1 :dep-1] "foo"
[:env-1 :dep-2] "bar"
[:env-2 :dep-3] "baz"}
:second-setting
{[:env-1 :dep-1] "quux"
[:env-1 :dep-2] "ni"
[:env-2 :dep-3] "ecky"}}
Note that the keys of the nested maps are vectors containing keywords which correspond to the environment (from the -e or --env command-line option) and the deployment (from the -d or --deployment command-line option), respectively. The app (from the -a or --app command-line option) is not currently used in this file.
The keywords at the first level of the map correspond directly to the placeholder names. When clavin defines the values that will be used by the template, it uses the keyword name with hyphens replaced with underscores as the placeholder name. For example, the :first-setting keyword mentioned above will be used to define the value of the first_setting placeholder. For example, suppose that you have the following template file:
some.service.first = $first_setting$
some.service.second = $second_setting$
Also suppose that you've chosen the environment, env-1 and the deployment dep-1 in the example environments file above. If a property file is generated from these settings, the resulting file would look like this:
some.service.first = foo
some.service.second = quux
In some cases, it's convenient to be able to generate deployment-specific settings from other deployment-specific settings. For example, a service generally has to be told which port to use for its listen port. In addition to this, clients of that service need to be given a base URL to use when connecting to this service. For this purpose, Clavin supports placeholders inside of property values:
{:foo-port
{[:env-1 :dep-1] "8888"}
:foo-base
{[:env-1 :dep-1] "http://somehost.example.org:${foo-port}/bar"}}
Note that the placeholder format is a little different in this file than it is in the configuration file templates. The reason for this difference was to make the substitution easier while still allowing idiomatic Clojure keywords to be used in the settings map.
Clavin also supports chained substitutions, in which the substituted value also contains a substitution string. Take this (admittedly contrived) environments file, for example:
{:foo-port
{[:env-1 :dep-1] "8888"}
:foo-host
{[:env-1 :dep-1] "somehost.example.org:${foo-port}"}
:foo-base
{[:env-1 :dep-1] "http://${foo-host}"}}
In this case, the value for the setting, foo-base, contains a reference to the setting, foo-host, which contains a reference to the setting, foo-port. There's no practical limit to the number of settings in the chain, but the chains should be kept as short as possible. An extremely long chain (or a recursive chain) will cause a stack overflow error in Clavin. Checks for recursive chains can be added sometime in the future if this begins to cause a problem.
Validating an Environments File
In order for an environments file to be useful, every environment has to have the same set of properties defined. Clavin provides a way to ensure that this is the case. Here's an example of a valid file check:
$ clavin envs -v -f environments.clj
environments.clj is valid.
Here's an example of an invalid file check:
$ clavin envs -v -f environments.clj
environments.clj is not valid.
Please check the following properties for the following environments:
:first-setting
:second-setting
[:dev :env-1]
[:deb :env-1]
[:dev :env-2]
[:dev :enb-2]
In this case, it appears that some of the environment names were mistyped in one or more properties.
Listing Environments in an Environments File
The environments file can get fairly big, so it's sometimes convenient to be able to list the environments that are defined within a file. The envs subcommand can be used for this purpose as well.
$ clavin envs -l -f environments.clj
environment deployment
----------- -----------
env-1 dep-1
env-1 dep-2
In this example, the environment definition file has one environment, env-1 containing two deployments, dep-1 and dep-2.
Loading properties into Zookeeper
You will need to have access to configuration file templates for the services you're going to load the confgurations for and an environment definition file that contains definitions for all of the placeholder values that are used in the configuration files. Then you can run the following command:
clavin props --host 127.0.0.1 --acl <path-to-acls-file> -f <path-to-environments-file> -t <path-to-template-dir> -a app -e dev -d dep-2 service-name1 service-name-2
The -a option refers to the app that you're loading configurations for. Currently, the Discovery Environment is the only application supported by Clavin, so the app will always be de. Because of this, the default value for the -a option is de and the -a option does not have to be specified.
The -e option refers to the environment that you're loading configurations for, which corresponds to the name of the environment in the environments file (or the environment and deployment listing described above). In cases where the deployment name is unique across all environments, the environment can be determined from the deployment name, so it's not necessary to specify the -e option unless another deployment of the same name appears in another environment.
The -d option refers to the deployment that you're loading configurations for. Once again, this is the same as the name of the deployment in the environments file (or the environment and deployment listing mentioned above). This option must correspond to one of the deployments defined in the environments file.
The values of the -a, -e, and -d options MUST correspond to a deployment listed in the ACLs file indicated with the --acl option. For instance, in the above example there must be a key of "app.dev.dep-2" with IP addresses associated with it in the --acl file. You will get a stack trace if it doesn't appear and nothing will get changed in Zookeeper.
The value of the -f flag should contain the path to the environment definition file and the value of the -t flag should contain the path to the directory containing the template files. Note that all of the template files must have an extension of .st and the name of the file without the extension corresponds to the name of the service that is being configured.
The service name arguments correspond to the names of the services whose configurations you want to load into Zookeeper. For example, if you wanted to load only the configurations for metadactyl and donkey, you would mention both services on the command line:
clavin props --host 127.0.0.1 --acl acls.properties -f environments.clj -t templates -d dep-2 metadactyl donkey
To load all of the properties files without having to list them all, you can simply not include any service names on the command line:
clavin props --host 127.0.0.1 --acl acls.properties -f environments.clj -t templates -d dep-2
Listing Configuration Settings in Zookeeper
Once configuration settings have been loaded into Zookeeper, you can list them using the get-props subcommand. Suppose that you wanted to list all of the configuration settings for the service, foo running on the local machine. The command to do that would look something like this:
clavin get-props --host 127.0.0.1 -s foo
The output from this command contains several lines containing the property name followed by some whitespace an equals sign and the property value. The output from the previous command could look something like this:
foo.app.listen-port = 65535
foo.bar.closing-time = 2:00
To improve the readability of the output, the equals signs are always aligned with the property names and property values left-justified in their respective columns.
If you're only interested in specific property values then you can specify the property names on the command line using unnamed arguments. For example, to explicitly list the foo.app.listen-port and foo.bar.closing-time properties from the example above, you could use something like this command:
clavin get-props --host 127.0.0.1 -s foo foo.app.listen-port foo.bar.closing-time
As a special case, the get-props subcommand will only display the property value if only one property name is specified. This is helpful for being able to access property values from within shell scripts without having to parse the output:
$ clavin get-props --host 127.0.0.1 -s foo foo.app.listen-port
65535
If you've read the previous sections, you may be wondering how Clavin determines which deployment to look up in Zookeeper. The answer is that it determines the deployment the same way that the services themselves do: by looking up the IP address of the service host in the ACLs stored in Zookeeper. The service host can be specified using the --service-host command-line option. If the --service-host option is not specified then the IP address of the local host will be used.
As with all subcommands, the -h or --help option can be used to display a brief usage message. This usage message contains brief descriptions of all of the command-line options.
Generating Properties Files
Not all iPlant services and web applications associated with the Discovery Environment use Zookeeper to manage configuration settings. For the components that do not use Zookeeper, Clavin provides a way to generate Java properties files from templates and environments files. The subcommand used to generate properties files is files. The command line for the files subcommand is similar to that of the props subcommand; the only differences are that the ACL and Zookeeper connection settings aren't required and a destination directory is required:
clavin files --dest <output-dir> -f <path-to-environments-file> -t <path-to-template-dir> -a app -e dev -d dep-2 service-name1 service-name-2
The only command-line option that is unique to the files subcommand is --dest, which is used to specify the path to the output directory. All of the generated properties files will be placed in this directory. The file names will be the service name with a .properties extension. For example, if you generate a properties file for the service, discoveryenvironment then the name of the generated file will be discoveryenvironment.properties.
See the Loading properties into Zookeeper section for details about the rest of the command-line options.
Clavin command-line
Running clavin with the help subcommand will list out the supported sub-tasks:
$ clavin help
clavin envs|files|help|hosts|props|templates [options]
Each command has its own --help.
Running clavin without any arguments will provide a brief error message along with the help text:
$ clavin
Something weird happened.
clavin envs|files|help|hosts|props|templates [options]
Each command has its own --help.
Currently, the supported subcommands are:
| Subcommand | Description |
|---|---|
| envs | Performs actions on environment files. |
| files | Generates properties files. |
| help | Displays a brief help message. |
| hosts | Loads admin ACLs into Zookeeper. |
| props | Loads configurations into Zookeeper. |
| templates | Performs actions on templates. |
Here's the help message for the envs subcommand:
$ clavin envs --help
Usage:
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show help.
-l, --no-list, --list false List environments.
-v, --no-validate, --validate false Validate the environments file
-f, --envs-file The file containing the environment definitions
Here's the help message for the files subcommand:
$ clavin files --help
Usage:
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show help.
-f, --envs-file The file containing the environment definitions.
-t, --template-dir The directory containing the templates.
-a, --app de The application the settings are for.
-e, --env The environment that the options are for.
-d, --deployment The deployment that the properties files are for.
--dest The destination directory for the files.
Here's the help message for the hosts subcommand:
$ clavin hosts --help
Usage:
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show help.
--acl The file containing Zookeeper hostname ACLs.
--host The Zookeeper host to connection to.
--port 31381 The Zookeeper client port to connection to.
-z, --zkhosts-path /etc/iplant-services/zkhosts.properties The path to the file containing the Zookeeper connection settings.
Here's the help message for the props subcommand:
$ clavin props --help
Usage:
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show help.
-f, --envs-file The file containing the environment definitions.
-t, --template-dir The directory containing the templates.
--host The Zookeeper host to connect to.
--port 31381 The Zookeeper client port to connect to.
-z, --zkhosts-path /etc/iplant-services/zkhosts.properties The path to the file containing the Zookeeper connection settings.
--acl The file containing Zookeeper hostname ACLs.
-a, --app de The application the settings are for.
-e, --env The environment that the options should be entered into.
-d, --deployment The deployment inside the environment that is being configured.
Here's the help message for the get-props subcommand:
$ clavin get-props --help
Usage:
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show help.
--host The Zookeeper host to connect to.
--port 31381 The Zookeeper port to connect to.
-z, --zkhosts-path /etc/iplant-services/zkhosts.properties The path to the file containing the Zookeeper connection settings.
-s, --service The service to get the settings for.
--service-host The host that the service is running on.
Here's the help message for the templates subcommand:
$ clavin templates --help
Usage:
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show help.
-l, --no-list, --list false List templates.
-v, --no-validate, --validate false Validate templates.
-t, --template-dir The directory containing the templates.
-f, --envs-file The file containing the environment definitions.
