About t he IdM Client T ools

IdM cre ate s a domain of re cognize d s e rvice s , hos t machine s , and us e rs with unive rs ally-applie d authe ntication s ource s and common policie s . From the pe rs pe ctive of a clie nt machine and an IdM us e r, the domain its e lf is fairly trans pare nt afte r the initial

configuration. All us e rs ne e d to do is log into the domain us ing Ke rbe ros , and that's it.

Howe ve r, an adminis trator has two ongoing tas ks : add principals to the IdM Ke rbe ros domain and s e t the domain policie s and s e rve r configuration that gove rn domain

inte ractions . Ide ntity Manage me nt has both command-line and we b-bas e d inte rface s for adminis trators to us e to manage the domain, s e rvice s , and IdM e ntrie s .

[1]

The mos t common me thod to maintain the domain is us ing the command-line tools . Ide ntity Manage me nt has an incre dibly broad s e t of s cripts and commands that are

available to adminis trators . The e ntry manage me nt functions of the domain are carrie d out with a s ingle s cript: ipa. This s cript is a pare nt or control s cript for as s ociate d

s ubcommands ; e ach s ubcommand re late s to a s pe cific e ntry type . The command-line s cripts offe r a numbe r of be ne fits :

The s cripts allow manage me nt tas ks to be automate d and pe rforme d re pe ate dly in a cons is te nt way without manual inte rve ntion.

Entrie s can be adde d with all pos s ible attribute s configure d (or a de s ire d s ubs e t of attribute s ) in a s ingle s te p. The we b UI fre que ntly re quire s two s te ps to fully configure an e ntry: the firs t to cre ate the e ntry and the ne xt to add optional attribute s .

The command-line s cripts s upport adding additional attribute s which may not be available in the UI or e ve n cus tom attribute s to e ntrie s , if the s che ma is configure d.

8.2.1. T he St ruct ure of t he ipa Command

The ipa command is e s s e ntially a big plug-in containe r. It s upports doze ns of

s ubcommands ; the s e s ubcommands are actually plug-ins which manage s pe cific type s of obje cts in Ide ntity Manage me nt.

The firs t type of a s ubcommand ide ntifie s the obje ct type (s uch as us e r, s udo, group, hos t, or dns ), and the s e cond part ide ntifie s the ope ration be ing pe rforme d on that obje ct.

ipa objectType-operation objectName -option=value

For e xample , adding a us e r is done us ing the user-add s ubcommand:

ipa user-add entryName options

Re late d s ubcommands are groupe d toge the r into plug-in modules. Commands for

managing DNS e ntrie s like dnszone-add and dnsrecord-add all be long to the dns module or topic. All of the information for managing a s pe cific are a, with all of the s upporte d commands and e xample s for e ach, are available by vie wing the he lp for that topic:

ipa help topic

TIP

To ge t a lis t of all available topics : ipa help topics

All topic or command are as follow a cons is te nt patte rn for how e ntrie s are manage d.

8.2.1.1. Adding, Editing, and Deleting Entries with ipa Ne w e ntrie s are adde d us ing an *-add command. For e xample :

⁠Chapt e r 8. T he Basics o f Managing t he IdM Se rve r and Se rvice s

$ ipa user-add jsmith

For add ope rations , commands us ually prompt for any re quire d configuration attribute s , which can be pas s e d as command-line options or us ing --set/addattr options

(Se ction 8.2.3, “Managing Entry Attribute s with --s e tattr, --addattr, and --de lattr”).

$ ipa user-add

ove rridde n with any *-find command with the --sizelimit and --timelimit options . For e xample , if the de fault time limit is 60 s e conds and a s e arch is going to take longe r, the

Whe n e ntrie s are re turne d, only ce rtain de fault attribute s are dis playe d with the e ntry; to re turn all attribute s curre ntly s e t for e ntrie s , us e the --all option.

To dis play a s pe cific e ntry, us e the *-show command and the e ntry name . As with

s e arche s , only a s ubs e t of attribute s is dis playe d with the e ntry unle s s the --all option is us e d.

8.2.1.3. Adding Members to Groups and Containers with ipa

Group me mbe rs are adde d and re move d with s e parate commands , apart from s imply modifying an e ntry. Me mbe r commands e s s e ntially cre ate a re lations hip be twe e n

diffe re nt IdM e ntrie s . While this is obvious in traditional group-me mbe r role s , it is als o true for s ome policy e ntrie s (like SELinux and s udo policie s ) whe re e ntrie s are as s ociate d with anothe r e ntry.

Mos t commonly, the command format for adding a me mbe r e ntry is *-add-member, although the command may s pe cify an e ntry type , s uch as *-add-user.

Like wis e , e ntrie s are re move d as me mbe rs (not de le te d) us ing a remove-member or *-remove-type command.

8.2.2. Posit ional Element s in ipa Commands

Us ually, ipa s ubcommands have only two e le me nts : the name of the e ntry be ing modifie d (the object) and the n any options available for the s ubcommand:

ipa command entryName --options=values --dynamic-update option with zone commands ; and a map ke y for an automount map is give n in the --key option.

Howe ve r, e ntrie s can als o allow attribute s that may not have command-line (or UI) options for s e tting the m. Partially, this is be caus e the unde rlying LDAP s che ma is ve ry rich,

particularly for us e r e ntrie s , with many pos s ible allowe d attribute s . Additionally,

⁠Chapt e r 8. T he Basics o f Managing t he IdM Se rve r and Se rvice s

Ide ntity Manage me nt allows s che ma e xte ns ions for us e rs and groups , and thos e cus tom s che ma e le me nts are not ne ce s s arily re fle cte d in the UI or command-line tools .

Any s upporte d attribute can be adde d or e dite d to an e ntry us ing the setattr and --addattr options .

IMPORTANT

The value of the attribute be ing adde d is not validate d by the modify command or the --setattr or --addattr options .

Both options have this format:

--setattr=attribute=value

The --setattr option s e ts one value for the give n attribute ; any e xis ting value s are ove rwritte n, e ve n for multi-value d attribute s .

The --addattr option adds a ne w value for an attribute ; for a multi-value d attribute , it adds the ne w value while pre s e rving any e xis ting value s .

Both --setattr option and --addattr can be us e d multiple time s in the s ame command invocation. For e xample :

$ ipa user-mod jsmith addattr=mail=johnnys@me.com

--addattr=mail=jsmith@example.com --setattr=description="backup IT manager for the east coast branch"

Like wis e , an attribute or s pe cific attribute value can be re move d from an e ntry us ing the --delattr option. For a s ingle -value d attribute , this re move s the attribute ; for a multi-value d attribute , it re move s only the s pe cifie d multi-value . For e xample :

$ ipa user-mod jsmith --delattr=mail=johnnys@me.com

NOTE

De le ting attribute s is e valuate d las t, afte r adding or e diting attribute s . If the s ame attribute is adde d and de le te d in the s ame modify ope ration, it is a no-op.

$ ipa user-mod jsmith addattr=mail=johnnys@me.com --delattr=mail=johnnys@me.com

8.2.4. Set t ing a List of Values

In LDAP, multi-value d attribute s have a s ingle attribute -value as s e rtion (attribute: value) that can be us e d multiple time s in an e ntry. For e xample :

mail: admin@example.com mail: jsmith@example.com

The re are s ome attribute s , howe ve r, whe re the value its e lf can contain a lis t. For

e xample , in IdM, the attribute s that are s e arche d whe n s e arching for us e rs or groups is de fine d in a lis t, not in multiple AVAs :

ipaUserSearchFields: uid,givenname,sn,telephonenumber,ou,title

This applie s to s e arch fie lds , pe rmis s ions and othe r acce s s control s e ttings , and s ome type s of group lis ts , like for s udo command groups , hos t-bas e d acce s s control rule s , and s e rvice groups .

Atte mpting to add a s ingle ite m to the lis t whe n modifying the e ntry ove rwrite s all pre vious s e ttings , be caus e the re is only a s ingle AVA. It is pos s ible to cre ate the lis t value in e ithe r of two ways :

Us e the s ame command-line argume nt multiple time s within the same command invocation. For e xample :

--permissions=read --permissions=write --permissions=delete Enclos e the lis t in curly brace s , which allows the s he ll to do the e xpans ion. For e xample :

--permissions={read,write,delete}

IMPORTANT

Whe n adding or updating an attribute with a lis t as a value , include e ve ry ite m in the lis t with the update . The lis t is update d e ve ry time , and any pre vious value is

ove rwritte n with the ne w update .

8.2.5. Using Special Charact ers wit h IdM T ools

The IdM command-line tools are run as any othe r utilitie s in a s he ll. If the re are s pe cial characte rs in the command — s uch as angle bracke ts (> and <), ampe rs ands (&),

as te ris ks (*), and pipe s (|) — the characte rs mus t be e s cape d. Othe rwis e , the command fails be caus e the s he ll cannot prope rly pars e the une s cape d characte rs .

8.2.6. Logging int o t he IdM Domain Before Running

Be fore running any IdM commands (with the e xce ption of the ins tallation s cripts , s uch as ipa-server-install), the us e r mus t firs t authe nticate to the IdM domain by obtaining a Ke rbe ros ticke t. This is done us ing kinit:

[jsmith@ipaserver ~]$ kinit admin

Diffe re nt login options are de s cribe d in Se ction 8.3, “Logging into IdM”.