CommandDocumentation#

Command-line Documentation Guidelnes#

IPA provides a set of command-line utilities that perform actions as varied as installing the product, managing replicas and administering the IPA data. The clearest differentiator is the command which executes these.

The ipa command executes data management commands (user, group, etc.) and the ipa- (dash) commands are generally used in a more limited way (e.g. ipa-server-install, ipa-replica-manage). I refer to these as the standalone commands.

Command types#

The standalone commands each have their own man page. This includes a description of what the command does and a list of the available options (and perhaps even an example or two).

The ipa command executes commands from the XML-RPC framework and manages data in the IPA database. There is a single man page for the ipa command with an overview of its capabilites, but not a complete list of all plugins and what their various options do.

Getting help#

ipa- commands#

To get help from a standalone command use either the –help option or see the man page:

% ipa-replica-manage --help
Usage: ipa-replica-manage [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -H HOST, --host=HOST  starting host
  -p DIRMAN_PASSWD, --password=DIRMAN_PASSWD
                        Directory Manager password
  -v, --verbose         provide additional information
  -f, --force           ignore some types of errors
  --port=PORT           port number of other server
  --binddn=BINDDN       Bind DN to use with remote server
  --bindpw=BINDPW       Password for Bind DN to use with remote server
  --winsync             This is a Windows Sync Agreement
  --cacert=CACERT       Full path and filename of CA certificate to use with
                        TLS/SSL to the remote server
  --win-subtree=WIN_SUBTREE
                        DN of Windows subtree containing the users you want to
                        sync (default cn=Users,<domain suffix)
  --passsync=PASSSYNC   Password for the Windows PassSync user

% man ipa-replica-manage

Framework commands (ipa)#

There are a number of different ways to get help from the ipa command.

The overall man page for the command:

% man ipa

Note that ipa –help and ipa help are two different, if confusing, things.

ipa --help provides assistance on using the ipa command itself.

ipa help provides assistance on the data management commands within ipa.

A list of available topics. A topic is a high-level view of the data management. For example user, group and host are topics.

% ipa help topics
Usage: ipa [global-options] COMMAND ...

Built-in commands:
  console     Start the IPA interactive Python console.
  help        Display help for a command or topic.
Help topics:
  aci         Directory Server Access Control Instructions (ACIs)
  automount   Automount
  cert        Command plugins for IPA-RA certificate operations.
  config      IPA configuration
  dns         Domain Name System (DNS) plugin
  group       Groups of users
  hbac        Host based access control
  host        Hosts/Machines (Identity)
  hostgroup   Groups of hosts.
  krbtpolicy  Kerberos ticket policy
  migration   Migration to IPA
  misc        Misc plugins
  netgroup    Netgroups
  passwd      Password changes
  pwpolicy    Password policy
  rolegroup   Rolegroups
  service     Services (Identity)
  taskgroup   Taskgroups
  user        Users (Identity)
Try `ipa --help` for a list of global options.`

To dive into a particular topic:

% ipa help user
Users (Identity)
Related commands:
  user-add     Create new user.
  user-del     Delete user.
  user-find    Search for users.
  user-lock    Lock user account.
  user-mod     Modify user.
  user-show    Display user.
  user-unlock  Unlock user account.

To get help on a particular framework command:

% ipa help user-add
Purpose: Create new user.
Usage: ipa [global-options] user-add LOGIN
Options:
  -h, --help       show this help message and exit
  --first=STR      First name
  --last=STR       Last name
  --homedir=STR    Home directory
  --gecos=STR      GECOS field
  --shell=STR      Login shell
  --principal=STR  Kerberos principal
  --email=STR      Email address
  --password       Set the user password
  --uid=INT        UID (use this option to set it manually)
  --street=STR     Street address
  --addattr=STR    Add an attribute/value pair. Format is attr=value
  --setattr=STR    Set an attribute to an name/value pair. Format is
                   attr=value
  --all            retrieve all attributes
  --raw            print entries as stored on the server

The framework commands are supposed to be self-documenting, with the ipa man page there to describe the basic layout of how things should work. Not all plugins currently have extra documentation but the goal is to have help like the dns plugin:

% ipa help dns
Domain Name System (DNS) plugin
Implements a set of commands useful for manipulating DNS records used by
the BIND LDAP plugin.
EXAMPLES:
 Add new zone;
   ipa dns-add example.com nameserver.example.com admin@example.com
 Add second nameserver for example.com:
   ipa dns-add-rr example.com @ NS nameserver2.example.com
 Delete previously added nameserver from example.com:
   ipa dns-del-rr example.com @ NS nameserver2.example.com
 Add new A record for www.example.com: (random IP)
   ipa dns-add-rr example.com www A 80.142.15.2
   ...
   ...

Rules of the Road#

Standalone commands#

Every standalone command must have:

A man page
Usage output

Framework commands#

Framework commands must have:

A single man page, ipa
Basic usage output for options, this is automatic (ipa user-add --help)
An overview of the command via ipa help <topic>

The overview comes from the initial docstring in the plugin itself. It should include:

User-understandable plugin name
Basic description of what the plugin does
Usage examples

CommandDocumentation

Contents