4.6. Command-line interface for domain management

udm is the command-line interface for domain management in Univention Directory Manager (UDM). Use it to automate administrative tasks in scripts and to integrate domain management into other programs. It’s an alternative to the web-based Management UI and its management modules.

Run the command as the root user on the Primary Directory Node with the univention-directory-manager command, or use the short form udm.

UDM and the web interface use the same domain management modules. As a result, the command-line interface provides the same functions as the web interface.

See also

Management module reference

in Nubus Manual 1.x [4] for the reference to the web-based management modules of UDM in the Management UI.

4.6.1. Parameters of the command-line interface

To list all available modules, run the command shown in Listing 4.17 with the modules parameter.

Listing 4.17 List available UDM modules

$ univention-directory-manager modules
Available Modules are:
  computers/computer
  computers/domaincontroller_backup
  computers/domaincontroller_master
  computers/domaincontroller_slave
  [...]

Every module has the following operations:

list, lookup

Lists all existing objects of this type.

create, new

Creates a new object.

modify, edit

Modifies an existing object.

remove, delete

Deletes an object.

move

Moves an object to another position in the LDAP directory.

restore

Restores an object from the Recycle Bin.

To view the options and operations for a UDM module, run the command shown in Listing 4.18 with the module name and the operation.

Listing 4.18 View options and operations for a UDM module

$ univention-directory-manager users/user move
[...]
general options:
  --binddn                         bind DN
  --bindpwd                        bind password (deprecated, use --bindpwdfile instead)
  --bindpwdfile                    file containing bind password
[...]
create options:
  --position                       Set position in tree
  --set                            Set variable to value, e.g. foo=bar
[...]
modify options:
  --dn                             Edit object with DN
  --set                            Set variable to value, e.g. foo=bar
[...]
remove options:
  --dn                             Remove object with DN
  --superordinate                  Use superordinate module
[...]
list options:
  --filter                         Lookup filter
  --position                       Search underneath of position in tree
[...]
move options:
  --dn                             Move object with DN
  --position                       Move to position in tree
[...]

To view all operations, options, and attributes for a module, run the command shown in Listing 4.19. Replace category/modulename with the module path, for example, users/user.

Listing 4.19 View all attributes for a UDM module

$ univention-directory-manager [category/modulename]

When using the udm create operation, you must specify all attributes marked with *.

Some attributes can have more than one value, for example, email addresses for user objects. The [] marker after an attribute name identifies a multi-value field. Some attributes require specific options for the object. To set an option for an individual attribute, enter the option name, as shown in Listing 4.20.

Listing 4.20 View variables for a UDM module

users/user variables:
  General:
    username (*)                             Username
[...]
  Contact:
    e-mail (person,[])                       E-Mail Address

Here, username (*) means that you must always set this attribute when you create user objects. When you enable the person option for the user account, which is the default, you can add one or more email addresses to the contact information.

The following common parameters are available, depending on the operation:

--binddn

Use this parameter to specify the bind DN for the LDAP connection.

Important

You usually don’t need --binddn when you run udm as root on a Nubus for UCS system. In that case, UDM tries to use local system credentials automatically.

Provide --binddn when you want to authenticate as a different LDAP account or when the default local credentials aren’t available or don’t have the required permissions.

--bindpwd

Use this parameter to specify the bind password for the LDAP connection.

Deprecated since version 5.2-4: --bindpwd is deprecated. Use --bindpwdfile instead.

--bindpwdfile

Use this parameter to specify a file that contains the bind password for --binddn.

Important

You usually don’t need --bindpwdfile when you run udm as root on a UCS system. If you don’t enter bind credentials, UDM tries to use local system credentials, such as the administrator account or the machine account.

Provide --bindpwdfile together with --binddn when you want to authenticate explicitly or when automatic local authentication isn’t available.

--logfile

Use this parameter to specify the path of the log file for the command. If you don’t enter --logfile, UDM writes to /var/log/univention/directory-manager-cmd.log.

--tls

Use this parameter to control StartTLS for the LDAP connection.

0

Don’t use StartTLS.

1

Try StartTLS.

2

Require StartTLS. This is default behavior, if you don’t provide --tls.

--dn

Use this parameter to specify the distinguished name (DN) of the object when you modify, delete, move, or restore it. Enter the complete DN, as shown in Listing 4.21.

Listing 4.21 Remove an object by DN

$ univention-directory-manager users/user remove \
  --dn "uid=ldapadmin,cn=users,dc=company,dc=example"

--position

Use this parameter to specify an LDAP position.

In the udm create operation, this parameter specifies where UDM creates the object. If you don’t enter --position, UDM creates the object under the module’s default LDAP base. If you use --superordinate without --position, UDM uses the superordinate DN as the position.

In the udm list operation, this parameter limits the search to objects below the specified LDAP position.

In the udm move operation, this parameter specifies the target position, as shown in Listing 4.22.

Listing 4.22 Move an object to another LDAP position

$ univention-directory-manager computers/ipmanagedclient move \
  --dn "cn=desk01,cn=management,cn=computers,dc=company,dc=com" \
  --position "cn=finance,cn=computers,dc=company,dc=example"

--set

Use this parameter to assign the given value to the following attribute. Use one --set parameter for each attribute-value pair, as shown in Listing 4.23.

Listing 4.23 Create a user with attribute values

$ univention-directory-manager users/user create \
  --position "cn=users,dc=company,dc=example" \
  --set username="jsmith" \
  --set firstname="John" \
  --set lastname="Smith" \
  --set password="12345678"

--append, --remove

Use --append or --remove to add or remove a value from a multi-value field, as shown in Listing 4.24.

Listing 4.24 Add and remove values in a multi-value field

$ univention-directory-manager groups/group modify \
  --dn "cn=staff,cn=groups,dc=company,dc=example" \
  --append users="uid=smith,cn=users,dc=company,dc=example" \
  --remove users="uid=miller,cn=users,dc=company,dc=example"

--option

Use this parameter to define the LDAP object classes for an object. For example, if you provide only the pki option for a user object, you can’t specify mailPrimaryAddress because this attribute belongs to the mail option.

--append-option, --remove-option

Use --append-option to add a module option to the current option set.

Use --remove-option to remove a module option from the current option set.

These parameters are useful when a module provides default options, and you want to adjust them for one command.

--superordinate

Use --superordinate when an object requires the DN of a parent object. For example, a DHCP object requires a DHCP service object. Pass the DN of that object with the --superordinate option.

For list operations, you can also use --superordinate to limit the lookup context for dependent objects.

--policy-reference

Use the --policy-reference parameter to assign a policy to an object. If you link a policy to an object, the object uses the policy settings, as shown in Listing 4.25. Replace category/modulename with the module path, and replace Operation with the operation that you want to run.

Repeat the parameter to assign more than one policy.

Listing 4.25 Assign a policy to an object

$ univention-directory-manager [category/modulename] [Operation] \
  --policy-reference "cn=sales,cn=pwhistory,cn=users,cn=policies,dc=company,dc=example"

--policy-dereference

Use the --policy-dereference parameter to remove a policy from an object.

Repeat the parameter to remove more than one policy reference.

--ignore_exists

The --ignore_exists parameter skips existing objects. If the object already exists, UDM still returns the error code 0 for no error.

--ignore_not_exists

Use this parameter with the udm modify or udm remove operation to ignore missing objects. If the object doesn’t exist, UDM doesn’t report an error.

--remove_referring

Use this parameter with the udm remove operation to remove referring objects during cleanup, if the module supports that cleanup.

--filter

Use this parameter to select objects with an LDAP filter.

With the udm list operation, UDM lists matching objects.

With the udm remove operation, UDM removes the matching object in the selected context. You can combine --filter with --dn or --position.

--policies

Use this parameter with the udm list operation to show policy-based settings.

If you don’t enter --policies, UDM doesn’t show policy-based settings.

0

Show a short form.

1

Show a long form that includes the policy DN.

--properties

Use this parameter with the udm list operation to limit the output to specific properties.

Repeat the parameter for each property that you want to show. If you don’t enter --properties, UDM shows all properties that are configured for list output.

4.6.2. Command-line interface examples

Use these examples as templates for your own scripts.

4.6.2.1. Users

This section lists examples of the udm working with the Users module.

• To create a user in the standard user container, run the udm create command shown in Listing 4.26.

  Listing 4.26 Create a user in the standard user container

  $ univention-directory-manager users/user create \
    --position "cn=users,dc=example,dc=com" \
    --set username="user01" \
    --set firstname="Random" \
    --set lastname="User" \
    --set organisation="Example company LLC" \
    --set mailPrimaryAddress="mail@example.com" \
    --set password="secretpassword"
  

• To add a postal address for an existing user, run the udm modify command shown in Listing 4.27.

  Listing 4.27 Add a postal address to an existing user

  $ univention-directory-manager users/user modify \
    --dn "uid=user01,cn=users,dc=example,dc=com" \
    --set street="Exemplary Road 42" \
    --set postcode="28239" \
    --set city="Bremen"
  

• To list all users whose username begins with user, run the udm list command shown in Listing 4.28.

  Listing 4.28 List users by username prefix

  $ univention-directory-manager users/user list \
    --filter uid='user*'
  

• To limit the search to a specific LDAP position, run the udm list command shown in Listing 4.29. This example lists all users in the cn=bremen,cn=users,dc=example,dc=com container.

  Listing 4.29 List users by username prefix in a specific container

  $ univention-directory-manager users/user list \
    --filter uid="user*" \
    --position "cn=bremen,cn=users,dc=example,dc=com"
  

• To remove the user user04, run the udm remove command shown in Listing 4.30.

  Listing 4.30 Remove a user

  $ univention-directory-manager users/user remove \
    --dn "uid=user04,cn=users,dc=example,dc=com"
  

• If your organization has two sites with separate containers, you can move a user from the Hamburg container to the Bremen container. Run the udm move command shown in Listing 4.31.

  Listing 4.31 Move a user between site containers

  $ univention-directory-manager users/user move \
    --dn "uid=user03,cn=hamburg,cn=users,dc=example,dc=com" \
    --position "cn=bremen,cn=users,dc=example,dc=com"
  

See also

Users module

in Nubus Manual 1.x [4] for information about the Users management module.

4.6.2.2. Groups

This section lists examples of the udm working with the Groups module.

• To create the group Example Users and add the user user01, run the udm create command shown in Listing 4.32.

  Listing 4.32 Create a group and add a user

  $ univention-directory-manager groups/group create \
    --position "cn=groups,dc=example,dc=com" \
    --set name="Example Users" \
    --set users="uid=user01,cn=users,dc=example,dc=com"
  

• To add the user user02 to the existing group, run the udm modify command shown in Listing 4.33.

  Listing 4.33 Add a user to an existing group

  $ univention-directory-manager groups/group modify \
    --dn "cn=Example Users,cn=groups,dc=example,dc=com" \
    --append users="uid=user02,cn=users,dc=example,dc=com"
  

  Caution

  A --set on the attribute users overwrites the list of group members in contrast to --append.

• To remove the user user01 from the group, run the udm modify command shown in Listing 4.34.

  Listing 4.34 Remove a user from a group

  $ univention-directory-manager groups/group modify \
    --dn "cn=Example Users,cn=groups,dc=example,dc=com" \
    --remove users="uid=user01,cn=users,dc=example,dc=com"
  

See also

Groups module

in Nubus Manual 1.x [4] for information about the Groups management module.

4.6.2.3. Containers

To create the cn=Bremen container under cn=computers for computers at the Bremen site, run the udm create command shown in Listing 4.35. The computerPath option also registers this container as the standard container for computer objects. For more information, see User-defined LDAP structures in Nubus Manual 1.x [4].

Listing 4.35 Create a container for a site

$ univention-directory-manager container/cn create \
  --position "cn=computers,dc=example,dc=com" \
  --set name="bremen" \
  --set computerPath=1

See also

LDAP directory module

in Nubus Manual 1.x [4] for information about the LDAP directory management module.

4.6.2.4. Policies

This section lists examples of the udm working with the Policies module.

• To create a user quota policy, run the udm create command shown in Listing 4.36.

  Listing 4.36 Create a user quota policy

  $ univention-directory-manager policies/share_userquota create \
    --position "cn=policies,dc=example,dc=com" \
    --set name="Default quota" \
    --set softLimitSpace=5GB \
    --set hardLimitSpace=10GB
  

• To link this policy to the user container cn=users, run the udm modify command shown in Listing 4.37.

  Listing 4.37 Link a policy to the user container

  $ univention-directory-manager container/cn modify \
    --dn "cn=users,dc=example,dc=com" \
    --policy-reference "cn=Default quota,cn=policies,dc=example,dc=com"
  

• To create a Univention Configuration Registry policy that sets the storage time for log files to one year, run the udm create command shown in Listing 4.38. Use one space to separate the variable name from its value.

  Listing 4.38 Create a UCR policy

  $ univention-directory-manager policies/registry create \
    --position "cn=config-registry,cn=policies,dc=example,dc=com" \
    --set name="default UCR settings" \
    --set registry="logrotate/rotate/count 52"
  

• To add another value to the UCR policy, run the udm modify command shown in Listing 4.39.

  Listing 4.39 Add a value to a UCR policy

  $ univention-directory-manager policies/registry modify \
    --dn "cn=default UCR settings,cn=config-registry,cn=policies,dc=example,dc=com" \
    --append registry='"logrotate/compress" "no"'
  

See also

Policies module

in Nubus Manual 1.x [4] for information about the Policies management module.

4.6.2.5. Computers

To create a Windows client account, run the udm create command shown in Listing 4.40. If the client joins the Samba domain later, as described in Windows domain joins, the domain join uses this computer account automatically:

Listing 4.40 Create a Windows client account

$ univention-directory-manager computers/windows create \
  --position "cn=computers,dc=example,dc=com" \
  --set name=WinClient01 \
  --set mac=aa:bb:cc:aa:bb:cc \
  --set ip=192.0.2.10

See also

Computers module

in Nubus Manual 1.x [4] for information about the Computers management module.

4.6.2.6. Shares

To create the Documentation share on fileserver.example.com, run the udm create command shown in Listing 4.41. If the /var/shares/documentation/ directory doesn’t exist on the server, UDM creates it automatically.

Listing 4.41 Create a share

$ univention-directory-manager shares/share create \
  --position "cn=shares,dc=example,dc=com" \
  --set name="Documentation" \
  --set host="fileserver.example.com" \
  --set path="/var/shares/documentation"

See also

Shares module

in Nubus Manual 1.x [4] for information about the Shares management module.

4.6.2.7. Printers

To create the printer share LaserPrinter01 on the print server printserver.example.com, run the udm create command shown in Listing 4.42. The PPD file defines the printer properties. Specify the PPD filename relative to /usr/share/ppd/. Ensure the printer is reachable over the network and supports the IPP protocol.

Listing 4.42 Create a printer share

$ univention-directory-manager shares/printer create \
  --position "cn=printers,dc=example,dc=com" \
  --set name="LaserPrinter01" \
  --set spoolHost="printserver.example.com" \
  --set uri="ipp:// 192.0.2.100" \
  --set model="foomatic-rip/HP-Color_LaserJet_9500-Postscript.ppd" \
  --set location="Head office" \
  --set producer="producer: cn=HP,cn=cups,cn=univention,dc=example,dc=com"

Note

Include a blank space between the print protocol and the target path in the uri parameter. For a list of print protocols, see Protocol and Destination in Nubus Manual 1.x [4].

You can group printers in a printer group to streamline administration. For more information about printer groups, see Printer groups. Before creating a printer group, ensure the printer shares you want to add already exist. To create a printer group, run the udm create command shown in Listing 4.43.

Listing 4.43 Create a printer group

$ univention-directory-manager shares/printergroup create \
  --position "cn=printers,dc=example,dc=com" \
  --set name=LaserPrinters \
  --set spoolHost="printserver.example.com" \
  --append groupMember=LaserPrinter01 \
  --append groupMember=LaserPrinter02

See also

Printers module

in Nubus Manual 1.x [4] for information about the Printers management module.

4.6.2.8. DNS and DHCP

To configure an IP assignment through DHCP, register a DHCP computer entry for the MAC address, as shown in Listing 4.44. For more information about DHCP, see IP assignment via DHCP.

Listing 4.44 Create a DHCP host entry

$ univention-directory-manager dhcp/host create \
  --superordinate "cn=example.com,cn=dhcp,dc=example,dc=com" \
  --set host="Client222" \
  --set fixedaddress="192.0.2.110" \
  --set hwaddress="ethernet 00:11:22:33:44:55"

To resolve a computer name through DNS, use the commands shown in Listing 4.45 and Listing 4.46 to configure forward resolution with a host record and reverse resolution with a PTR record. For more information about DNS, see Administration of DNS data with BIND.

Listing 4.45 Create a DNS host record

$ univention-directory-manager dns/host_record create \
  --superordinate "zoneName=example.com,cn=dns,dc=example,dc=com" \
  --set name="Client222" \
  --set a="192.0.2.110"

Listing 4.46 Create a DNS PTR record

$ univention-directory-manager dns/ptr_record create \
  --superordinate "zoneName=0.168.192.in-addr.arpa,cn=dns,dc=example,dc=com" \
  --set address="110" \
  --set ptr_record="Client222.example.com."

See also

DHCP module

in Nubus Manual 1.x [4] for information about the DHCP management module.

DNS module

in Nubus Manual 1.x [4] for information about the DNS management module.

4.6.2.9. Extended attributes

Use extended attributes to add fields to management modules in the Management UI. For more information, see Expand management modules. To add a new attribute that stores the license plate number of a company car for each user, run the udm create command shown in Listing 4.47. The object class univentionFreeAttributes stores these values.

Listing 4.47 Create an extended attribute

$ univention-directory-manager settings/extended_attribute create \
  --position "cn=custom attributes,cn=univention,dc=example,dc=com" \
  --set name="CarLicense" \
  --set module="users/user" \
  --set ldapMapping="univentionFreeAttribute1" \
  --set objectClass="univentionFreeAttributes" \
  --set longDescription="License plate number of the company car" \
  --set tabName="Company car" \
  --set multivalue=0 \
  --set syntax="string" \
  --set shortDescription="Car license"

See also

Expand management modules

in Nubus Manual 1.x [4] for information about how to expand management modules.