Skip to content

Latest commit

 

History

History
182 lines (141 loc) · 7.52 KB

installation.md

File metadata and controls

182 lines (141 loc) · 7.52 KB
Raw

Installation

Hammer CLI is packaged for the following RPM based distributions:

  • RHEL and derivatives, version 6
  • Fedora 18, 19
  • Debian Wheezy, Squeezy
  • Ubuntu Precise

Select your way of installation

Configuration

Locations

Configuration is by default looked for in the following directories, loaded in this order:

  • RbConfig::CONFIG['sysconfdir']/hammer/ (The actual value depends on your operatingsystem and ruby defaults.)
  • /etc/hammer/
  • ~/.hammer/
  • ./config/ (config dir in CWD)
  • custom location (file or directory) specified on command line - -c CONF_FILE_PATH

In each of these directories hammer is trying to load cli_config.yml and anything in the cli.modules.d subdirectory which is place for specific configuration of hammer modules a.k.a. plugins.

Later directories and files have precedence if they redefine the same option. Files from cli.modules.d are loaded in alphabetical order. The modules are loaded in alphabetical order which can be overriden with explicit requirement of dependences in the modules.

Manual installation

The packaged version of hammer copies the template to /etc/hammer for you. When you install from gems or source you'll have to copy config files manually.

The configuration templates are contained in the hammer_cli gem

gem contents hammer_cli|grep template.yml

and can be copied to one of the locations above and changed as needed.

Tuning options

Hammer uses YAML formatting for its configuration.

List of existing options is available in the configuration template file with descriptions.

Plugins

Plugins are disabled by default. To enable plugin create configuration file in cli.modules.d and add:enable_module: true in it. Plugin specific configuration must be nested under plugin's name (without the hammer_cli_ prefix).

In the example we assume the gem hammer_cli_foreman with the Foreman plugin is installed. Then the plugin configuration in ~/.hammer/cli.modules.d/foreman.yml should look as follows:

:foreman:
    :enable_module: true
    :host: 'https://localhost/'
    :username: 'admin'
    :password: 'changeme'

Use the hammer

Confirm your setup by running $ hammer -h and check that the desired commands are listed.

$ hammer -h
Usage:
    hammer [OPTIONS] SUBCOMMAND [ARG] ...

Parameters:
    SUBCOMMAND                    subcommand
    [ARG] ...                     subcommand arguments

Subcommands:
    architecture                  Manipulate architectures.
    compute-resource              Manipulate compute resources.
    domain                        Manipulate domains.
    environment                   Manipulate environments.
    fact                          Search facts.
    global-parameter              Manipulate global parameters.
    host                          Manipulate hosts.
    hostgroup                     Manipulate hostgroups.
    location                      Manipulate locations.
    medium                        Manipulate installation media.
    model                         Manipulate hardware models.
    organization                  Manipulate organizations.
    os                            Manipulate operating system.
    partition-table               Manipulate partition tables.
    proxy                         Manipulate smart proxies.
    puppet-class                  Search puppet modules.
    report                        Browse and read reports.
    sc-param                      Manipulate smart class parameters.
    shell                         Interactive shell
    subnet                        Manipulate subnets.
    template                      Manipulate config templates.
    user                          Manipulate users.

Options:
    --autocomplete LINE           Get list of possible endings
    --csv                         Output as CSV (same as --output=csv)
    --csv-separator SEPARATOR     Character to separate the values
    --interactive INTERACTIVE     Explicitly turn interactive mode on/off
                                  One of true/false, yes/no, 1/0.
    --output ADAPTER              Set output format. One of [silent, csv, base, table]
    --show-ids                    Show ids of associated resources
    --version                     show version
    -c, --config CFG_FILE         path to custom config file
    -h, --help                    print help
    -p, --password PASSWORD       password to access the remote system
    -u, --username USERNAME       username to access the remote system
    -v, --verbose                 be verbose

And you are done. Your hammer client is configured and ready to use.

Autocompletion

The completion offers suggestion of possible command-line subcommands and their options as usual. It can also suggest values for options and params where file or directory path is expected.

Bash completion is automatically installed by RPM. To use it for development setup cp ./config/hammer.completion /etc/bash_completion.d/hammer and load it to the current shell source /etc/bash_completion.d/hammer. Make sure the $PWD/bin is in PATH or there is full path to hammer-complete executable specified in /etc/bash_completion.d/hammer.

Bash completion for hammer needs pre-built cache that holds description of all subcommands and its parameters. The cache is located by default in ~/.cache/hammer_completion.json. The location can be changed in hammer's config file. The cache can be built manually with hammer prebuild-bash-completion or is built automatically when completion is used and the cache is missing (this may cause slight delay). The cache expires if your API cache was changed (it indicates that the features on the instance may have changed which has impact on hammer CLI options and subcommands).

Available value types

Completion of values is dependent on CLI option and prameter settings, e.g.:

  option '--value', 'VALUE', 'One of a, b, c', completion: { type: :enum, values: %w[a b c] }

Possible options for the :completion attribute are:

  • { type: :flag } option has no value, default for flags.
  • { type: :value } option has value of unknown type, no suggestions for the value, default.
  • { type: :list } option has value of list type, no suggestions for the value.
  • { type: :key_value_list } option has value of key=value list type, no suggestions for the value.
  • { type: :directory } value is directory, suggestions follow directory structure.
  • { type: :file, filter: '\.txt$' } value is file, suggestions follow directory structure, optional :filter is regexp to filter the results.
  • { type: :enum, values: ['first', 'second']} option can have one of the listed values, suggestions follow specified values.
  • { type: :multienum, values: ['first', 'second']} option can have one or more of the listed values, suggestions follow specified values.
  • { type: :schema, schema: 'a=int\,b=string' } option should have value according to specified schema, suggestion is the specified schema.

All those completion attributes are generated automatically, specify you own to override.