1ipa(1)                         IPA Manual Pages                         ipa(1)
2
3
4

NAME

6       ipa - IPA command-line interface
7

SYNOPSIS

9       ipa [options] [-c FILE] [-e KEY=VAL] COMMAND [parameters]
10

DESCRIPTION

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
18       This manual page focuses on the ipa script that serves as the main com‐
19       mand-line interface (CLI) for IPA administration.
20
21       More information about the project is available on its homepage located
22       at http://www.freeipa.org.
23

OPTIONS

25       -c FILE
26              Load configuration from FILE.
27
28       -d, --debug
29              Produce full debugging output.
30
31       --delegate
32              Delegate the user's TGT to the IPA server
33
34       -e KEY=VAL
35              Set  environmental  variable  KEY  to the value VAL. This option
36              overrides configuration files.
37
38       -h, --help
39              Display a help message with a list of options.
40
41       -n, --no-prompt
42              Don't prompt for any parameters of COMMAND,  even  if  they  are
43              required.
44
45       -a, --prompt-all
46              Prompt for all parameters of COMMAND, even if they are optional.
47
48       -f, --no-fallback
49              Don't  fall  back  to  other  IPA servers if the default doesn't
50              work.
51
52       -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
57       --version
58              Display the IPA version and API version.
59

COMMANDS

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
66       From the implementation perspective, the CLI distinguishes two types of
67       commands - built-ins and plugin provided.
68
69       Built-in commands are static and are all available in all installations
70       of IPA. There are two of them:
71
72       console
73              Start the IPA interactive Python console.
74
75       help [TOPIC | COMMAND | topics | commands]
76              Display help for a command or topic.
77
78              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
85       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
89       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
99       The following actions are available for most IPA object types:
100
101       add [PRIMARYKEY] [options]
102              Create a new object.
103
104       show [PRIMARYKEY] [options]
105              Display an existing object.
106
107       mod [PRIMARYKEY] [options]
108              Modify an existing object.
109
110       del [PRIMARYKEY]
111              Delete an existing object.
112
113       find [CRITERIA] [options]
114              Search for existing objects.
115
116       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
122       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
129       For  IPA  objects  with attributes that can contain references to other
130       objects (e.g. groups), the following action are usually available:
131
132       add-member [PRIMARYKEY] [options]
133              Add references to other objects.
134
135       remove-member [PRIMARYKEY] [options]
136              Remove references to other objects.
137
138       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
144       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
152       All commands that display objects have three special options  for  con‐
153       trolling output:
154
155       --all  Display  all attributes. Without this option only the most rele‐
156              vant attributes are displayed.
157
158       --raw  Display objects as they are stored in the  backing  store.  Dis‐
159              ables formatting and attribute labels.
160
161       --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
170              r - read
171              s - search
172              w - write
173              o - obliterate (delete)
174              c - compare
175              W - self-write
176              O - self-obliterate
177
178

EXAMPLES

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
185       ipa env
186              List IPA environmental variables and their values.
187
188       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
192       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
196       ipa group-add-member bar --users=foo
197              Add user "foo" to the group "bar".
198
199       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
203       ipa user-show foo --raw
204              Display user "foo" as (s)he is stored on the server.
205
206       ipa group-show bar --all
207              Display group "bar" and all of its attributes.
208
209       ipa config-mod --maxusername 20
210              Set maximum user name length to 20 characters.
211
212       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
217       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
222       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
226       ipa user-find
227              All users would match the search criteria (as there are none).
228

SERVERS

230       The ipa client will determine which server to connect to in this order:
231
232
233       1. The server configured in /etc/ipa/default.conf in the xmlrpc_uri
234       directive.
235
236       2. An unordered list of servers from the ldap DNS SRV records.
237
238
239       If a kerberos error is raised by any of the requests then it will stop
240       processing and display the error message.
241

ENVIRONMENT VARIABLES

243       IPA_CONFDIR
244              Override path to confdir (default: /etc/ipa).
245

FILES

247       /etc/ipa/default.conf
248              IPA default configuration file.
249

EXIT STATUS

251       0 if the command was successful
252
253       1 if an error occurred
254
255       2 if an entry is not found
256

SEE ALSO

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)
263
264
265
266
267IPA                               Apr 29 2016                           ipa(1)
Impressum