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.
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-replica-manage). I refer to these as the standalone commands.
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).
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.
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
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 firstname.lastname@example.org 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 220.127.116.11 ... ...
Rules of the Road
Every standalone command must have:
- A man page
- Usage output
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