QA:Testcase freeipav2 help

{{QA/Test_Case 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.
 * description=


 * setup=
 * 1) Make sure you have a working FreeIPA server (see QA:Testcase_freeipav2_installation)


 * actions=

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 . 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  -add for adding a new object  -del</tt> for deleting it etc.

Most topic commands that deal with a single object instance (-add</tt>, -del</tt>, -show</tt> 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</tt> 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</tt> output MUST have a separate help invoked by ipa help </tt>. Every topic command MUST print detailed usage information when invoked with --help</tt>.

All the test steps should end with the specified results. }}
 * results=