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, NTP and DNS. It includes a web
15 interface and command-line administration tools for managing identity
16 data.
17 This manual page focuses on the ipa script that serves as the main com‐
19 mand-line interface (CLI) for IPA administration.
20 More information about the project is available on its homepage located
22 at http://www.freeipa.org.
23
25 -c FILE
26 Load configuration from FILE.
27 -d, --debug
29 Produce full debugging output.
30 --delegate
32 Delegate the user's TGT to the IPA server
33 -e KEY=VAL
35 Set environmental variable KEY to the value VAL. This option
36 overrides configuration files.
37 -h, --help
39 Display a help message with a list of options.
40 -n, --no-prompt
42 Don't prompt for any parameters of COMMAND, even if they are
43 required.
44 -a, --prompt-all
46 Prompt for all parameters of COMMAND, even if they are optional.
47 -f, --no-fallback
49 Don't fall back to other IPA servers if the default doesn't
50 work.
51 -v, --verbose
53 Produce verbose output. A second -v pretty-prints the JSON
54 request and response. A third -v displays the HTTP request and
55 response.
56 --version
58 Display the IPA version and API version.
59
61 The principal function of the CLI is to execute administrative commands
62 specified by the COMMAND argument. The majority of commands are exe‐
63 cuted remotely over XML-RPC on a IPA server listed in the configuration
64 file (see FILES section of this manual page).
65 From the implementation perspective, the CLI distinguishes two types of
67 commands - built-ins and plugin provided.
68 Built-in commands are static and are all available in all installations
70 of IPA. There are two of them:
71 console
73 Start the IPA interactive Python console.
74 help [TOPIC | COMMAND | topics | commands]
76 Display help for a command or topic.
77 The help command invokes the built-in documentation system.
79 Without parameters a list of built-in commands and help topics
80 is displayed. Help topics are generated from loaded IPA plugin
81 modules. Executing help with the name of an available topic dis‐
82 plays a help message provided by the corresponding plugin module
83 and list of commands it contains.
84 Plugin provided commands, as the name suggests, originate from IPA
86 plugin modules. The available set may vary depending on your configura‐
87 tion and can be listed using the built-in help command (see above).
88 Most plugin provided commands are tied to a certain type of IPA object.
90 IPA objects encompass common abstractions such as users (user identi‐
91 ties/accounts), hosts (machine identities), services, password poli‐
92 cies, etc. Commands associated with an object are easily identified
93 thanks to the enforced naming convention; the command names are com‐
94 posed of two parts separated with a dash: the name of the corresponding
95 IPA object type and the name of action performed on it. For example all
96 commands used to manage user identities start with "user-" (e.g.
97 user-add, user-del).
98 The following actions are available for most IPA object types:
100 add [PRIMARYKEY] [options]
102 Create a new object.
103 show [PRIMARYKEY] [options]
105 Display an existing object.
106 mod [PRIMARYKEY] [options]
108 Modify an existing object.
109 del [PRIMARYKEY]
111 Delete an existing object.
112 find [CRITERIA] [options]
114 Search for existing objects.
115 The above types of commands except find take the objects primary key
117 (e.g. user name for users) as their only positional argument unless
118 there can be only one object of the given type. They can also take a
119 number of options (some of which might be required in the case of add)
120 that represent the objects attributes.
121 find commands take an optional criteria string as their only positional
123 argument. If present, all objects with an attribute that contains the
124 criteria string are displayed. If an option representing an attribute
125 is set, only object with the attribute exactly matching the specified
126 value are displayed. Options with empty values are ignored. Without
127 parameters all objects of the corresponding type are displayed.
128 For IPA objects with attributes that can contain references to other
130 objects (e.g. groups), the following action are usually available:
131 add-member [PRIMARYKEY] [options]
133 Add references to other objects.
134 remove-member [PRIMARYKEY] [options]
136 Remove references to other objects.
137 The above types of commands take the objects primary key as their only
139 positional argument unless there can be only one object of the given
140 type. They also take a number of options that represent lists of other
141 object primary keys. Each of these options represent one type of
142 object.
143 For some types of objects, these commands might need to take more than
145 one primary key. This applies to IPA objects organized in hierarchies
146 where the parent object needs to be identified first. Parent primary
147 keys are always aligned to the left (higher in the hierarchy = more to
148 the left). For example the automount IPA plugin enables users to manage
149 automount maps per location, as a result all automount commands take an
150 automountlocation primary key as their first positional argument.
151 All commands that display objects have three special options for con‐
153 trolling output:
154 --all Display all attributes. Without this option only the most rele‐
156 vant attributes are displayed.
157 --raw Display objects as they are stored in the backing store. Dis‐
159 ables formatting and attribute labels.
160 --rights
162 Display effective rights on all attributes of the entry. You
163 also have to specify --all for this to work. User rights are
164 returned as Python dictionary where index is the name of an
165 attribute and value is a unicode string composed (hence the
166 u'xxxx' format) of letters specified below. Note that user
167 rights are primarily used for internal purposes of CLI and
168 WebUI.
169 r - read
171 s - search
172 w - write
173 o - obliterate (delete)
174 c - compare
175 W - self-write
176 O - self-obliterate
177
180 ipa help commands
181 Display a list of available commands ipa help topics Display a
182 high-level list of help topics ipa help user Display documenta‐
183 tion and list of commands in the "user" topic.
184 ipa env
186 List IPA environmental variables and their values.
187 ipa user-add foo --first foo --last bar
189 Create a new user with username "foo", first name "foo" and last
190 name "bar".
191 ipa group-add bar --desc "this is an example group"
193 Create a new group with name "bar" and description "this is an
194 example group".
195 ipa group-add-member bar --users=foo
197 Add user "foo" to the group "bar".
198 ipa group-add-member bar --users={admin,foo}
200 Add users "admin" and "foo" to the group "bar". This approach
201 depends on shell expansion feature.
202 ipa user-show foo --raw
204 Display user "foo" as (s)he is stored on the server.
205 ipa group-show bar --all
207 Display group "bar" and all of its attributes.
208 ipa config-mod --maxusername 20
210 Set maximum user name length to 20 characters.
211 ipa user-find foo
213 Search for all users with "foo" in either uid, first name, last
214 name, full name, etc. A user with uid "foobar" would match the
215 search criteria.
216 ipa user-find foo --first bar
218 Same as the previous example, except this time the users first
219 name has to be exactly "bar". A user with uid "foobar" and first
220 name "bar" would match the search criteria.
221 ipa user-find foo --first bar --last foo
223 A user with uid "foobar", first name "bar" and last name "foo"
224 would match the search criteria.
225 ipa user-find
227 All users would match the search criteria (as there are none).
228
230 The ipa client will determine which server to connect to in this order:
231 1. The server configured in /etc/ipa/default.conf in the xmlrpc_uri
234 directive.
235 2. An unordered list of servers from the ldap DNS SRV records.
237 If a kerberos error is raised by any of the requests then it will stop
240 processing and display the error message.
241
243 IPA_CONFDIR
244 Override path to confdir (default: /etc/ipa).
245
247 /etc/ipa/default.conf
248 IPA default configuration file.
249
251 0 if the command was successful
252 1 if an error occurred
254 2 if an entry is not found
256
258 ipa-client-install(1), ipa-compat-manage(1), ipactl(1),
259 ipa-dns-install(1), ipa-getcert(1), ipa-getkeytab(1), ipa-join(1),
260 ipa-ldap-updater(1), ipa-nis-manage(1), ipa-replica-install(1),
261 ipa-replica-manage(1), ipa-replica-prepare(1), ipa-rmkeytab(1),
262 ipa-server-certinstall(2), ipa-server-install(1), ipa-server-upgrade(1)
263IPA Apr 29 2016 ipa(1)