From Fedora Project Wiki

Revision as of 16:36, 14 February 2011 by Jcholast (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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

  1. 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.