Description
There are two basic types of documented commands in FreeIPA - standalone executables and ipa plugins. The standalone executables are documented with manual pages, the ipa plugins are documented using a built-in help system.
Setup
- Make sure you have a working FreeIPA server (see QA:Testcase_freeipav2_installation)
How to test
Standalone executables
The standalone commands are used mostly during installation of FreeIPA server or client. Examples include /usr/sbin/ipa-server-install or /usr/sbin/ipa-getkeytab. Every standalone executable MUST have a manual page describing its usage and its command line options. Manual pages SHOULD contain examples where appropriate.
As of Feb 2011, the list of executables is:
/usr/sbin/ipa-client-install /usr/sbin/ipa-getkeytab /usr/sbin/ipa-join /usr/sbin/ipa-rmkeytab /usr/sbin/ipa-compat-manage /usr/sbin/ipa-host-net-manage /usr/sbin/ipa-ldap-updater /usr/sbin/ipa-nis-manage /usr/sbin/ipa-compliance /usr/sbin/ipa-dns-install /usr/sbin/ipa-replica-install /usr/sbin/ipa-replica-manage /usr/sbin/ipa-replica-prepare /usr/sbin/ipa-server-certinstall /usr/sbin/ipa-server-install /usr/sbin/ipa-upgradeconfig /usr/sbin/ipa_kpasswd /usr/sbin/ipactl /usr/bin/ipa
A special case of a standalone executable is /usr/bin/ipa. Its purpose is to be an entry point into the FreeIPA command line administration plugins which are discussed below.
ipa plugin
Most of the functionality that FreeIPA provides is implemented using a pluggable interface which allows to add new funcionality easily. There is a plugin for every part of functionality FreeIPA has - like managing users, managing hosts etc. The help for plugins is part of the plugins itself, there is no separate manual page. The manual page for ipa only discusses global options, like -d for debugging output and also provides a nice introduction into the plugin system and how ipa is controlled.
To see the list of topics, type ipa help into a terminal. The output should be something like:
$ ipa help Usage: ipa [global-options] COMMAND ... Built-in commands: Help subtopics: console Start the IPA interactive Python console. Help subtopics: help Display help for a command or topic. Help topics: automount Automount cert IPA certificate operations config Manage the IPA configuration delegation Group to Group Delegation dns Domain Name System (DNS) group Groups of users hbac Host based access control commands host Hosts/Machines hostgroup Groups of hosts. krbtpolicy Kerberos ticket policy migration Migration to IPA misc Misc plugins netgroup Netgroups passwd Set a user's password permission Permissions ping Ping the remote IPA server pkinit Kerberos pkinit options privilege Privileges pwpolicy Password policy role Roles selfservice Self-Service Permissions service Services sudo commands for controlling sudo configuration user Users
Every topic has a separate help, too, which can be invoked with ipa help <topic>. Try it with users, for example:
$ ipa help user Users Manage user entries. All users are POSIX users. IPA supports a wide range of username formats, but you need to be aware of any restrictions that may apply to your particular environment. For example, usernames that starts with a digit or usernames that exceed a certain length may cause problems for some UNIX systems. Use 'ipa config-mod' to change the username format allowed by IPA tools. Disabling a user account prevents that user from obtaining new Kerberos credentials. It does not invalidate any credentials that have already been issued. (trimmed down, the output is quite lengthy) Topic commands: user-add Add a new user. user-del Delete a user. user-disable Disable user account. user-enable Enable user account. user-find Search for users. user-mod Modify a user. user-show Display information about a user. user-unlock Lock user account
At the bottom of the output, you can see all the commands the plugin provides. Because most of the plugins support a very similar set of operations on the object they manage, you'll notice the topic commands are quite similar for most plugins. There's usually <topic>-add for adding a new object <topic>-del for deleting it etc.
Most topic commands that deal with a single object instance (-add, -del, -show etc.) accept a primary key identifying the object as their only positional argument. Examples of primary key include username for user objects or hostname for host object. The topic commands can usually take a number of options to fine tune the action performed. To see detailed synopsis of a command, invoke it with --help option:
$ ipa user-add --help Usage: ipa [global-options] user-add LOGIN [options] Options: -h, --help show this help message and exit --first=STR First name --last=STR Last name --cn=STR Full name --displayname=STR Display name --initials=STR Initials --homedir=STR Home directory --gecos=STR GECOS field --shell=STR Login shell --principal=STR Kerberos principal --email=STR Email address
Every plugin that IPA presents in the ipa help output MUST have a separate help invoked by ipa help <topic>. Every topic command MUST print detailed usage information when invoked with --help.
Expected Results
All the test steps should end with the specified results.