1ipa(1)                       FreeIPA 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 and DNS. It includes a web inter‐
15       face and command-line administration tools for managing identity data.
16
17       This manual page focuses on the ipa script that serves as the main com‐
18       mand-line interface (CLI) for IPA administration.
19
20       More information about the project is available on its homepage located
21       at http://www.freeipa.org.
22

OPTIONS

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

COMMANDS

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
65       From the implementation perspective, the CLI distinguishes two types of
66       commands - built-ins and plugin provided.
67
68       Built-in commands are static and are all available in all installations
69       of IPA. There are two of them:
70
71       console
72              Start the IPA interactive Python console.
73
74       help [TOPIC | COMMAND | topics | commands]
75              Display help for a command or topic.
76
77              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
84       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
88       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
98       The following actions are available for most IPA object types:
99
100       add [PRIMARYKEY] [options]
101              Create a new object.
102
103       show [PRIMARYKEY] [options]
104              Display an existing object.
105
106       mod [PRIMARYKEY] [options]
107              Modify an existing object.
108
109       del [PRIMARYKEY]
110              Delete an existing object.
111
112       find [CRITERIA] [options]
113              Search for existing objects.
114
115       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
121       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
126       parameters all objects of the corresponding type are displayed.
127
128       For IPA objects with attributes that can contain  references  to  other
129       objects (e.g. groups), the following action are usually available:
130
131       add-member [PRIMARYKEY] [options]
132              Add references to other objects.
133
134       remove-member [PRIMARYKEY] [options]
135              Remove references to other objects.
136
137       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
141       object.
142
143       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
151       All  commands  that display objects have three special options for con‐
152       trolling output:
153
154       --all  Display all attributes. Without this option only the most  rele‐
155              vant attributes are displayed.
156
157       --raw  Display  objects  as  they are stored in the backing store. Dis‐
158              ables formatting and attribute labels.
159
160       --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
163              returned as Python dictionary where index  is  the  name  of  an
164              attribute  and  value  is  a  unicode string composed (hence the
165              u'xxxx' format) of  letters  specified  below.  Note  that  user
166              rights  are  primarily  used  for  internal  purposes of CLI and
167              WebUI.
168
169              r - read
170              s - search
171              w - write
172              o - obliterate (delete)
173              c - compare
174              W - self-write
175              O - self-obliterate
176
177

EXAMPLES

179       ipa help commands
180              Display a list of available commands ipa help topics Display a
181              high-level list of help topics ipa help user Display documenta‐
182              tion and list of commands in the "user" topic.
183
184       ipa env
185              List IPA environmental variables and their values.
186
187       ipa user-add foo --first foo --last bar
188              Create a new user with username "foo", first name "foo" and last
189              name "bar".
190
191       ipa group-add bar --desc "this is an example group"
192              Create a new group with name "bar" and description "this is an
193              example group".
194
195       ipa group-add-member bar --users=foo
196              Add user "foo" to the group "bar".
197
198       ipa group-add-member bar --users={admin,foo}
199              Add users "admin" and "foo" to the group "bar". This approach
200              depends on shell expansion feature.
201
202       ipa user-show foo --raw
203              Display user "foo" as (s)he is stored on the server.
204
205       ipa group-show bar --all
206              Display group "bar" and all of its attributes.
207
208       ipa config-mod --maxusername 20
209              Set maximum user name length to 20 characters.
210
211       ipa user-find foo
212              Search for all users with "foo" in either uid, first name, last
213              name, full name, etc. A user with uid "foobar" would match the
214              search criteria.
215
216       ipa user-find foo --first bar
217              Same as the previous example, except this time the users first
218              name has to be exactly "bar". A user with uid "foobar" and first
219              name "bar" would match the search criteria.
220
221       ipa user-find foo --first bar --last foo
222              A user with uid "foobar", first name "bar" and last name "foo"
223              would match the search criteria.
224
225       ipa user-find
226              All users would match the search criteria (as there are none).
227

SERVERS

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

ENVIRONMENT VARIABLES

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

FILES

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

EXIT STATUS

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

SEE ALSO

257       ipa-client-install(1), ipa-compat-manage(1), ipactl(1),
258       ipa-dns-install(1), ipa-getcert(1), ipa-getkeytab(1), ipa-join(1),
259       ipa-ldap-updater(1), ipa-nis-manage(1), ipa-replica-install(1),
260       ipa-replica-manage(1), ipa-replica-prepare(1), ipa-rmkeytab(1),
261       ipa-server-certinstall(2), ipa-server-install(1), ipa-server-upgrade(1)
262
263
264
265FreeIPA                           Apr 29 2016                           ipa(1)
Impressum