From Fedora Project Wiki

(Created page with '{{QA/Test_Case |description=FreeIPA runtime documentation. |setup= # Make sure you have a working FreeIPA server (see QA:Testcase_freeipav2_installation) |actions= There are ...')
 
m
Line 120: Line 120:
 
   --principal=STR    Kerberos principal
 
   --principal=STR    Kerberos principal
 
   --email=STR        Email address
 
   --email=STR        Email address
 +
 +
</ol>
  
 
|results=
 
|results=

Revision as of 16:06, 14 February 2011

Description

FreeIPA runtime documentation.

Setup

  1. Make sure you have a working FreeIPA server (see QA:Testcase_freeipav2_installation)

How to test

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.

  1. Standalone executables
  2. 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.

    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.

  3. ipa plugin
  4. 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
    

Expected Results

  1. Every standalone executable MUST have a manual page describing its usage and its command line options. Manual pages SHOULD contain examples where appropriate.
  2. 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.