[Freeipa-devel] [DOC] about netgroups

[Pavel Zůna]

I was asked to complete the documentation of IPA commands on the 
internal wiki. Unfortunatly, I currently don't have access to it and 
have decided to put some of the information I've been gathering here on 
freeipa-devel. It's not a secret after all and is easier to review by 
other team members. I'm going to put this on the wiki as soon as I can.

So, in the first (and possibly last) issue of CommandDocs(tm), we're 
going to look at netgroups and commands related to them.

What are netgroups?
===================
Netgroups are a concept introduced in the directory service NIS. They 
are supposed to contain users, hosts (machines) and other netgroups. 
Here are a few examples of why such groups can be useful:

http://directory.fedoraproject.org/wiki/Howto:Netgroups#What_are_NIS_netgroups_good_for.3F

Don't continue reading after the "What are NIS netgroups good for?" 
part. Netgroup entries are different in IPA.

Some more info about netgroups (optional reading; I'll explain most of 
the important stuff):
http://www.softpanorama.org/Net/Application_layer/NIS/nis_netgroups.shtml

How do we store netgroups in the IPA backend (LDAP)?
====================================================
NIS groups traditionally contain a so called netgroup triple of the format:

(machine, user, domain)

machine - machine name, a host name
user - user name
domain - NIS domain of the machine and user

Note that there is no necessary relationship between the machine and the 
user. Only one of those fields is usually used at a time to avoid 
confusion.

In IPA, we don't use the triple anymore. It's ugly and unclear. Instead 
we use the membership relationship between LDAP entries. You simple add 
users, host and even their groups as members of a netgroup. The domain 
field is constant for each netgroup and defaults to the current IPA domain.

Example of a netgroup displayed using the IPA CLI:

# ipa netgroup-show net1
   Netgroup name: net1
   Description: test netgroup
   NIS domain name: pzuna
   Member User: admin
   Member Host: testbox.pzuna

What commands are available in IPA for handling netgroups?
==========================================================
The management plugin for netgroups in IPA conforms to the CRUD command 
naming conventions used in all other plugins, that come with the default
IPA installation.

Creating new netgroups
----------------------
  ipa netgroup-add NAME [--desc=DESCRIPTION] [--nisdomain=NISDOMAIN]

NAME is the name of the netgroup (can be anything, but must be unique)
DESCRIPTION is the netgroup description (required)
NISDOMAIN is the NIS domain name, defaults to the current IPA domain

Deleting netgroups
------------------
  ipa netgroup-del NAME

Displaying netgroups
--------------------
  ipa netgroup-show NAME

Modifying netgroups
-------------------
  ipa netgroup-mod NAME [--desc=DESCRIPTION] [--nisdomain=NISDOMAIN]

Same as `ipa netgroup-add`, except modifying description is required and 
NISDOMAIN doesn't default to anything.

Searching for netgroups
-----------------------
  ipa netgroup-find [CRITERIA] [--name=NAME] [--desc=DESCRIPTION]
                               [--nisdomain=NISDOMAIN] [--uuid=UUID]

CRITERIA is an optional substring, that has to appear in either the 
name, the description or the NIS domain of the groups you're looking for

Other options are the same as `ipa netgroup-add`, except nothing is 
required and doesn't default to anything. There's a new UUID option, 
that allows searching netgroups by ipaUniqueID. If one of these options 
is set, the command returns only exact matches of this option.

Adding users and hosts to netgroups
-----------------------------------
  ipa netgroup-add-member NAME [--users=USERS] [--groups=GROUPS]
                               [--hosts=HOSTS] [--hostgroups=HOSTGROUPS]
                               [--netgroups=NETGROUPS]

USERS,GROUPS,HOSTS,HOSTGROUPS,NETGROUPS are comma-separated lists of 
names of the appropriate objects.

Removing users and hosts from netgroups
---------------------------------------
  ipa netgroup-remove-member NAME [--users=USERS] [--groups=GROUPS]
                                  [--hosts=HOSTS]
                                  [--hostgroups=HOSTGROUPS]
                                  [--netgroups=NETGROUPS]

Same as `netgroup-add-member`.

Examples
--------
# ipa netgroup-add net0 --desc="test netgroup"
   Netgroup name: net0
   Description: test netgroup
   NIS domain name: pzuna
   IPA unique ID: 9e6e089c-2089-11df-b677-5452004c033a

# ipa netgroup-mod net0 --desc="description change"
   Netgroup name: net0
   Description: description change
   NIS domain name: pzuna

# ipa netgroup-add-member net0 --users=admin --hosts=testbox.pzuna
   Netgroup name: net0
   Description: description change
   NIS domain name: pzuna
   Member User: admin
   Member Host: testbox.pzuna
-------------------------
Number of members added 2
-------------------------

# ipa netgroup-remove-member net0 --users=admin
   Netgroup name: net0
   Description: description change
   NIS domain name: pzuna
   Member Host: testbox.pzuna
---------------------------
Number of members removed 1
---------------------------

# ipa netgroup-del net0

# ipa netgroup-show net0
ipa: ERROR: no such entry



Pavel