Chapter 1. Introduction to the IdM command-line utilities
Chapter 1. Introduction to the IdM command-line utilities Learn more about the basics of using the Identity Management (IdM) command-line utilities. Prerequisites Installed and accessible IdM server. For details, see Installing Identity Management . To use the IPA command-line interface, authenticate to IdM with a valid Kerberos ticket. 1.1. What is the IPA command-line interface The IPA command-line interface (CLI) is the basic command-line interface for Identity Management (IdM) administration. It supports a lot of subcommands for managing IdM, such as the ipa user-add command to add a new user. IPA CLI allows you to: Add, manage, or remove users, groups, hosts and other objects in the network. Manage certificates. Search entries. Display and list objects. Set access rights. Get help with the correct command syntax. 1.2. What is the IPA help The IPA help is a built-in documentation system for the IdM server. The IPA command-line interface (CLI) generates available help topics from loaded IdM plugin modules. To use the IPA help utility, you must: Have an IdM server installed and running. Be authenticated with a valid Kerberos ticket. Entering the ipa help command without options displays information about basic help usage and the most common command examples. You can use the following options for different ipa help use cases: [] - Brackets mean that all parameters are optional and you can write just ipa help and the command will be executed. | - The pipe character means or . Therefore, you can specify a TOPIC , a COMMAND , or topics , or commands , with the basic ipa help command: topics - You can run the command ipa help topics to display a list of topics that are covered by the IPA help, such as user , cert , server and many others. TOPIC - The TOPIC with capital letters is a variable. Therefore, you can specify a particular topic, for example, ipa help user . commands - You can enter the command ipa help commands to display a list of commands which are covered by the IPA help, for example, user-add , ca-enable , server-show and many others. COMMAND - The COMMAND with capital letters is a variable. Therefore, you can specify a particular command, for example, ipa help user-add . 1.3. Using IPA help topics The following procedure describes how to use the IPA help on the command line. Procedure Open a terminal and connect to the IdM server. Enter ipa help topics to display a list of topics covered by help. Select one of the topics and create a command according to the following pattern: ipa help [topic_name] . Instead of the topic_name string, add one of the topics you listed in the step. In the example, we use the following topic: user If the IPA help output is too long and you cannot see the whole text, use the following syntax: You can then scroll down and read the whole help. The IPA CLI displays a help page for the user topic. After reading the overview, you can see many examples with patterns for working with topic commands. 1.4. Using IPA help commands The following procedure describes how to create IPA help commands on the command line. Procedure Open a terminal and connect to the IdM server. Enter ipa help commands to display a list of commands covered by help. Select one of the commands and create a help command according to the following pattern: ipa help <COMMAND> . Instead of the <COMMAND> string, add one of the commands you listed in the step. Additional resources ipa man page on your system 1.5. Structure of IPA commands The IPA CLI distinguishes the following types of commands: Built-in commands - Built-in commands are all available in the IdM server. Plug-in provided commands The structure of IPA commands allows you to manage various types of objects. For example: Users, Hosts, DNS records, Certificates, and many others. For most of these objects, the IPA CLI includes commands to: Add ( add ) Modify ( mod ) Delete ( del ) Search ( find ) Display ( show ) Commands have the following structure: ipa user-add , ipa user-mod , ipa user-del , ipa user-find , ipa user-show ipa host-add , ipa host-mod , ipa host-del , ipa host-find , ipa host-show ipa dnsrecord-add , ipa dnsrecord-mod , ipa dnsrecord-del , ipa dnsrecord-find , ipa dnrecord-show You can create a user with the ipa user-add [options] , where [options] are optional. If you use just the ipa user-add command, the script asks you for details one by one. Note that the [options] --raw and --structured are mutually exclusive and should not be run together. To change an existing object, you need to define the object, therefore the command also includes an object: ipa user-mod USER_NAME [options] . 1.6. Using an IPA command to add a user account to IdM The following procedure describes how to add a new user to the Identity Management (IdM) database using the command line. Prerequisites You need to have administrator privileges to add user accounts to the IdM server. Procedure Open a terminal and connect to the IdM server. Enter the command for adding a new user: The command runs a script that prompts you to provide basic data necessary for creating a user account. In the First name: field, enter the first name of the new user and press the Enter key. In the Last name: field, enter the last name of the new user and press the Enter key. In the User login [suggested user name]: enter the user name, or just press the Enter key to accept the suggested user name. The user name must be unique for the whole IdM database. If an error occurs because that user name already exists, repeat the process with the ipa user-add command and use a different, unique user name. After you add the user name, the user account is added to the IdM database and the IPA command-line interface (CLI) prints the following output: Note By default, a user password is not set for the user account. To add a password while creating a user account, use the ipa user-add command with the following syntax: The IPA CLI then prompts you to add or confirm a user name and password. If the user has been created already, you can add the password with the ipa user-mod command. Additional resources Run the ipa help user-add command for more information about parameters. 1.7. Using an IPA command to modify a user account in IdM You can change many parameters for each user account. For example, you can add a new password to the user. Basic command syntax is different from the user-add syntax because you need to define the existing user account for which you want to perform changes, for example, add a password. Prerequisites You need to have administrator privileges to modify user accounts. Procedure Open a terminal and connect to the IdM server. Enter the ipa user-mod command, specify the user to modify, and any options, such as --password for adding a password: The command runs a script where you can add the new password. Enter the new password and press the Enter key. The IPA CLI prints the following output: The user password is now set for the account and the user can log into IdM. Additional resources Run the ipa help user-mod command for more information about parameters. 1.8. How to supply a list of values to the IdM utilities Identity Management (IdM) stores values for multi-valued attributes in lists. IdM supports the following methods of supplying multi-valued lists: Using the same command-line argument multiple times within the same command invocation: Alternatively, you can enclose the list in curly braces, in which case the shell performs the expansion: The examples above show a command permission-add which adds permissions to an object. The object is not mentioned in the example. Instead of ... you need to add the object for which you want to add permissions. When you update such multi-valued attributes from the command line, IdM completely overwrites the list of values with a new list. Therefore, when updating a multi-valued attribute, you must specify the whole new list, not just a single value you want to add. For example, in the command above, the list of permissions includes reading, writing and deleting. When you decide to update the list with the permission-mod command, you must add all values, otherwise those not mentioned will be deleted. Example 1: - The ipa permission-mod command updates all previously added permissions. or Example 2 - The ipa permission-mod command deletes the --right=delete argument because it is not included in the command: or 1.9. How to use special characters with the IdM utilities When passing command-line arguments that include special characters to the ipa commands, escape these characters with a backslash (\). For example, common special characters include angle brackets (< and >), ampersand (&), asterisk (*), or vertical bar (|). For example, to escape an asterisk (*): Commands containing unescaped special characters do not work as expected because the shell cannot properly parse such characters.
ipa help [TOPIC | COMMAND | topics | commands] ipa help topics ipa help user ipa help user | less ipa help commands ipa help user-add ipa user-add ---------------------- Added user "euser" ---------------------- User login: euser First name: Example Last name: User Full name: Example User Display name: Example User Initials: EU Home directory: /home/euser GECOS: Example User Login shell: /bin/sh Principal name: euser@IDM.EXAMPLE.COM Principal alias: euser@IDM.EXAMPLE.COM Email address: euser@idm.example.com UID: 427200006 GID: 427200006 Password: False Member of groups: ipausers Kerberos keys available: False ipa user-add --first=Example --last=User --password ipa user-mod euser --password ---------------------- Modified user "euser" ---------------------- User login: euser First name: Example Last name: User Home directory: /home/euser Principal name: euser@IDM.EXAMPLE.COM Principal alias: euser@IDM.EXAMPLE.COM Email address: euser@idm.example.com UID: 427200006 GID: 427200006 Password: True Member of groups: ipausers Kerberos keys available: True ipa permission-add --right=read --permissions=write --permissions=delete ipa permission-add --right={read,write,delete} ipa permission-mod --right=read --right=write --right=delete ipa permission-mod --right={read,write,delete} ipa permission-mod --right=read --right=write ipa permission-mod --right={read,write} ipa certprofile-show certificate_profile --out= exported\*profile.cfg