1ipa(1) IPA Manual Pages ipa(1)
2
6 ipa - IPA command-line interface
7
9 ipa [options] [-c FILE] [-e KEY=VAL] COMMAND [parameters]
10
12 IPA is an integrated security information management solution based on
13 389 Directory Server (formerly know as Fedora Directory Server), MIT
14 Kerberos, Dogtag Certificate System and DNS. It includes a web inter‐
15 face and command-line administration tools for managing identity data.
16 This manual page focuses on the ipa script that serves as the main com‐
18 mand-line interface (CLI) for IPA administration.
19 More information about the project is available on its homepage located
21 at http://www.freeipa.org.
22
24 -c FILE
25 Load configuration from FILE.
26 -d, --debug
28 Produce full debugging output.
29 --delegate
31 Delegate the user's TGT to the IPA server
32 -e KEY=VAL
34 Set environmental variable KEY to the value VAL. This option
35 overrides configuration files.
36 -h, --help
38 Display a help message with a list of options.
39 -n, --no-prompt
41 Don't prompt for any parameters of COMMAND, even if they are re‐
42 quired.
43 -a, --prompt-all
45 Prompt for all parameters of COMMAND, even if they are optional.
46 -f, --no-fallback
48 Don't fall back to other IPA servers if the default doesn't
49 work.
50 -v, --verbose
52 Produce verbose output. A second -v pretty-prints the JSON re‐
53 quest and response. A third -v displays the HTTP request and re‐
54 sponse.
55 --version
57 Display the IPA version and API version.
58
60 The principal function of the CLI is to execute administrative commands
61 specified by the COMMAND argument. The majority of commands are exe‐
62 cuted remotely over XML-RPC on a IPA server listed in the configuration
63 file (see FILES section of this manual page).
64 From the implementation perspective, the CLI distinguishes two types of
66 commands - built-ins and plugin provided.
67 Built-in commands are static and are all available in all installations
69 of IPA. There are two of them:
70 console
72 Start the IPA interactive Python console.
73 help [TOPIC | COMMAND | topics | commands]
75 Display help for a command or topic.
76 The help command invokes the built-in documentation system.
78 Without parameters a list of built-in commands and help topics
79 is displayed. Help topics are generated from loaded IPA plugin
80 modules. Executing help with the name of an available topic dis‐
81 plays a help message provided by the corresponding plugin module
82 and list of commands it contains.
83 Plugin provided commands, as the name suggests, originate from IPA
85 plugin modules. The available set may vary depending on your configura‐
86 tion and can be listed using the built-in help command (see above).
87 Most plugin provided commands are tied to a certain type of IPA object.
89 IPA objects encompass common abstractions such as users (user identi‐
90 ties/accounts), hosts (machine identities), services, password poli‐
91 cies, etc. Commands associated with an object are easily identified
92 thanks to the enforced naming convention; the command names are com‐
93 posed of two parts separated with a dash: the name of the corresponding
94 IPA object type and the name of action performed on it. For example all
95 commands used to manage user identities start with "user-" (e.g.
96 user-add, user-del).
97 The following actions are available for most IPA object types:
99 add [PRIMARYKEY] [options]
101 Create a new object.
102 show [PRIMARYKEY] [options]
104 Display an existing object.
105 mod [PRIMARYKEY] [options]
107 Modify an existing object.
108 del [PRIMARYKEY]
110 Delete an existing object.
111 find [CRITERIA] [options]
113 Search for existing objects.
114 The above types of commands except find take the objects primary key
116 (e.g. user name for users) as their only positional argument unless
117 there can be only one object of the given type. They can also take a
118 number of options (some of which might be required in the case of add)
119 that represent the objects attributes.
120 find commands take an optional criteria string as their only positional
122 argument. If present, all objects with an attribute that contains the
123 criteria string are displayed. If an option representing an attribute
124 is set, only object with the attribute exactly matching the specified
125 value are displayed. Options with empty values are ignored. Without pa‐
126 rameters all objects of the corresponding type are displayed.
127 For IPA objects with attributes that can contain references to other
129 objects (e.g. groups), the following action are usually available:
130 add-member [PRIMARYKEY] [options]
132 Add references to other objects.
133 remove-member [PRIMARYKEY] [options]
135 Remove references to other objects.
136 The above types of commands take the objects primary key as their only
138 positional argument unless there can be only one object of the given
139 type. They also take a number of options that represent lists of other
140 object primary keys. Each of these options represent one type of ob‐
141 ject.
142 For some types of objects, these commands might need to take more than
144 one primary key. This applies to IPA objects organized in hierarchies
145 where the parent object needs to be identified first. Parent primary
146 keys are always aligned to the left (higher in the hierarchy = more to
147 the left). For example the automount IPA plugin enables users to manage
148 automount maps per location, as a result all automount commands take an
149 automountlocation primary key as their first positional argument.
150 All commands that display objects have three special options for con‐
152 trolling output:
153 --all Display all attributes. Without this option only the most rele‐
155 vant attributes are displayed.
156 --raw Display objects as they are stored in the backing store. Dis‐
158 ables formatting and attribute labels.
159 --rights
161 Display effective rights on all attributes of the entry. You
162 also have to specify --all for this to work. User rights are re‐
163 turned as Python dictionary where index is the name of an attri‐
164 bute and value is a unicode string composed (hence the u'xxxx'
165 format) of letters specified below. Note that user rights are
166 primarily used for internal purposes of CLI and WebUI.
167 r - read
169 s - search
170 w - write
171 o - obliterate (delete)
172 c - compare
173 W - self-write
174 O - self-obliterate
175
178 ipa help commands
179 Display a list of available commands
180 ipa help topics
182 Display a high-level list of help topics
183 ipa help user
185 Display documentation and list of commands in the "user" topic.
186 ipa env
188 List IPA environmental variables and their values.
189 ipa user-add foo --first foo --last bar
191 Create a new user with username "foo", first name "foo" and last
192 name "bar".
193 ipa group-add bar --desc "this is an example group"
195 Create a new group with name "bar" and description "this is an
196 example group".
197 ipa group-add-member bar --users=foo
199 Add user "foo" to the group "bar".
200 ipa group-add-member bar --users={admin,foo}
202 Add users "admin" and "foo" to the group "bar". This approach
203 depends on shell expansion feature.
204 ipa user-show foo --raw
206 Display user "foo" as (s)he is stored on the server.
207 ipa group-show bar --all
209 Display group "bar" and all of its attributes.
210 ipa config-mod --maxusername 20
212 Set maximum user name length to 20 characters.
213 ipa user-find foo
215 Search for all users with "foo" in either uid, first name, last
216 name, full name, etc. A user with uid "foobar" would match the
217 search criteria.
218 ipa user-find foo --first bar
220 Same as the previous example, except this time the users first
221 name has to be exactly "bar". A user with uid "foobar" and first
222 name "bar" would match the search criteria.
223 ipa user-find foo --first bar --last foo
225 A user with uid "foobar", first name "bar" and last name "foo"
226 would match the search criteria.
227 ipa user-find
229 All users would match the search criteria (as there are none).
230
232 The ipa client will determine which server to connect to in this order:
233 1. The server configured in /etc/ipa/default.conf in the xmlrpc_uri di‐
236 rective.
237 2. An unordered list of servers from the ldap DNS SRV records.
239 If a kerberos error is raised by any of the requests then it will stop
242 processing and display the error message.
243
245 IPA_CONFDIR
246 Override path to confdir (default: /etc/ipa).
247
249 /etc/ipa/default.conf
250 IPA default configuration file.
251
253 0 if the command was successful
254 1 if an error occurred
256 2 if an entry is not found
258
260 ipa-client-install(1), ipa-compat-manage(1), ipactl(1), ipa-dns-in‐
261 stall(1), ipa-getcert(1), ipa-getkeytab(1), ipa-join(1), ipa-ldap-up‐
262 dater(1), ipa-nis-manage(1), ipa-replica-install(1), ipa-replica-man‐
263 age(1), ipa-replica-prepare(1), ipa-rmkeytab(1), ipa-server-certin‐
264 stall(2), ipa-server-install(1), ipa-server-upgrade(1)
265IPA Apr 29 2016 ipa(1)