NAME

SYNOPSIS

adcli info domain.example.com

adcli join domain.example.com

adcli update

adcli testjoin

adcli create-user [--domain=domain.example.com] user

adcli delete-user [--domain=domain.example.com] user

adcli create-group [--domain=domain.example.com] user

adcli delete-group [--domain=domain.example.com] user

adcli add-member [--domain=domain.example.com] group user...

adcli remove-member [--domain=domain.example.com] group user...

adcli preset-computer [--domain=domain.example.com] computer...

adcli reset-computer [--domain=domain.example.com] computer

adcli delete-computer [--domain=domain.example.com] computer

adcli show-computer [--domain=domain.example.com] computer

adcli create-msa [--domain=domain.example.com]

GENERAL OVERVIEW

See the various sub commands below. The following global options can be used:

-D, --domain=domain

-R, --domain-realm=REALM

-S, --domain-controller=server

--use-ldaps

$ LDAPTLS_CACERT=/path/to/ad_dc_ca_cert.pem adcli join --use-ldaps -D domain.example.com
...

-C

--login-ccache[=ccache_name]

-U, --login-user=User

--no-password

-W, --prompt-password

--stdin-password

-v, --verbose

QUERYING DOMAIN INFORMATION

$ adcli info domain.example.com
...

$ adcli info --domain-controller=dc.domain.example.com
...

adcli info will output as much information as it can about the domain. The information is designed to be both machine and human readable. The command will exit with a non-zero exit code if the domain does not exist or cannot be reached.

To show domain info for a specific domain controller use the --domain-controller option to specify which domain controller to query.

Use the --verbose option to show details of how the domain is discovered and queried. Many of the global options, in particular authentication options, are not usable with the adcli info command.

JOINING THE LOCAL MACHINE TO A DOMAIN

$ adcli join domain.example.com
Password for Administrator:

In addition to the global options, you can specify the following options to control how this operation is done.

-N, --computer-name=computer

-O, --domain-ou=OU=xxx

-H, --host-fqdn=host

-K, --host-keytab=/path/to/keytab

--login-type={computer|user}

--os-name=name

--os-service-pack=pack

--os-version=version

--description=description

--service-name=service

--user-principal=host/name@REALM

--one-time-password

--trusted-for-delegation=yes|no|true|false

--add-service-principal=service/hostname

--show-details

--show-password

--add-samba-data

--samba-data-tool=/path/to/net

If supported on the AD side the msDS-supportedEncryptionTypes attribute will be set as well. Either the current value or the default list of AD's supported encryption types filtered by the permitted encryption types of the client's Kerberos configuration are written.

UPDATING THE MACHINE ACCOUNT PASSWORD AND OTHER ATTRIBUTES

$ adcli update

If used with a credential cache, other attributes of the computer account can be changed as well if the principal has sufficient privileges.

$ kinit Administrator
$ adcli update --login-ccache=/tmp/krbcc_123

In addition to the global options, you can specify the following options to control how this operation is done.

-N, --computer-name=computer

-H, --host-fqdn=host

-K, --host-keytab=/path/to/keytab

--os-name=name

--os-service-pack=pack

--os-version=version

--description=description

--service-name=service

--user-principal=host/name@REALM

--computer-password-lifetime=lifetime

--trusted-for-delegation=yes|no|true|false

--account-disable=yes|no|true|false

--add-service-principal=service/hostname

--remove-service-principal=service/hostname

--show-details

--add-samba-data

--samba-data-tool=/path/to/net

If supported on the AD side the msDS-supportedEncryptionTypes attribute will be set as well. Either the current value or the default list of AD's supported encryption types filtered by the permitted encryption types of the client's Kerberos configuration are written.

TESTING IF THE MACHINE ACCOUNT PASSWORD IS VALID

$ adcli testjoin

Only the global options not related to authentication are available, additionally you can specify the following options to control how this operation is done.

-K, --host-keytab=/path/to/keytab

CREATING A USER

$ adcli create-user Fry --domain=domain.example.com \
	--display-name="Philip J. Fry" --mail=fry@domain.example.com

In addition to the global options, you can specify the following options to control how the user is created.

--display-name="Name"

-O, --domain-ou=OU=xxx

--mail=email@domain.com

--unix-home=/home/user

--unix-gid=111

--unix-shell=/bin/shell

--unix-uid=111

--nis-domain=nis_domain

DELETING A USER

$ adcli delete-user Fry --domain=domain.example.com

The various global options can be used.

CREATING A GROUP

$ adcli create-group Pilots --domain=domain.example.com \
	--description="Group for all pilots"

In addition to the global options, you can specify the following options to control how the group is created.

--description="text"

-O, --domain-ou=OU=xxx

DELETING A GROUP

$ adcli delete-group Pilots --domain=domain.example.com

The various global options can be used.

ADDING A MEMBER TO A GROUP

$ adcli add-member --domain=domain.example.com Pilots Leela Scruffy

The various global options can be used.

REMOVING A MEMBER FROM A GROUP

$ adcli remove-member --domain=domain.example.com Pilots Scruffy

The various global options can be used.

PRESET COMPUTER ACCOUNTS

$ adcli preset-computer --domain=domain.example.com \
	host1.example.com host2
Password for Administrator:

If the computer names specified contain dots, then they are treated as fully qualified host names, otherwise they are treated as short computer names. The computer accounts must not already exist.

In addition to the global options, you can specify the following options to control how this operation is done.

-O, --domain-ou=OU=xxx

--one-time-password

--os-name=name

--os-service-pack=pack

--os-version=version

--service-name=service

--user-principal

RESET COMPUTER ACCOUNT

$ adcli reset-computer --domain=domain.example.com host2

If the computer names specified contain dots, then they are treated as fully qualified host names, otherwise they are treated as short computer names.

In addition to the global options, you can specify the following options to control how this operation is done.

--login-type={computer|user}

DELETE COMPUTER ACCOUNT

$ adcli delete-computer --domain=domain.example.com host2
Password for Administrator:

If the computer name contains a dot, then it is treated as fully qualified host name, otherwise it is treated as short computer name.

If no computer name is specified, then the host name of the computer adcli is running on is used, as returned by gethostname().

The various global options can be used.

SHOW COMPUTER ACCOUNT ATTRIBUTES

$ adcli show-computer --domain=domain.example.com host2
Password for Administrator:

If the computer name contains a dot, then it is treated as fully qualified host name, otherwise it is treated as short computer name.

If no computer name is specified, then the host name of the computer adcli is running on is used, as returned by gethostname().

The various global options can be used.

CREATE A MANAGED SERVICE ACCOUNT

$ adcli create-msa --domain=domain.example.com
Password for Administrator:

The managed service account, as maintained by adcli, cannot have additional service principals names (SPNs) associated with it. An SPN is defined within the context of a Kerberos service which is tied to a machine account in Active Directory. Since a machine can be joined to a single Active Directory domain, managed service account in a different Active Directory domain will not have the SPNs that otherwise are part of another Active Directory domain's machine.

Since it is expected that a client will most probably join to the Active Directory domain matching its DNS domain the managed service account will be needed for a different Active directory domain and as a result the Active Directory domain name is a mandatory option. If called with no other options adcli create-msa will use the short hostname with an additional random suffix as computer name to avoid name collisions.

LDAP attribute sAMAccountName has a limit of 20 characters. However, machine account's NetBIOS name must be at most 16 characters long, including a trailing '$' sign. Since it is not expected that the managed service accounts created by adcli will be used on the NetBIOS level the remaining 4 characters can be used to add uniqueness. Managed service account names will have a suffix of 3 random characters from number and upper- and lowercase ASCII ranges appended to the chosen short host name, using '!' as a separator. For a host with the shortname 'myhost', a managed service account will have a common name (CN attribute) 'myhost!A2c' and a NetBIOS name (sAMAccountName attribute) will be 'myhost!A2c$'. A corresponding Kerberos principal in the Active Directory domain where the managed service account was created would be 'myhost!A2c$@DOMAIN.EXAMPLE.COM'.

A keytab for the managed service account is stored into a file specified with -K option. If it is not specified, the file is named after the default keytab file, with lowercase Active Directory domain of the managed service account as a suffix. On most systems it would be /etc/krb5.keytab with a suffix of 'domain.example.com', e.g. /etc/krb5.keytab.domain.example.com.

adcli create-msa can be called multiple times to reset the password of the managed service account. To identify the right account with the random component in the name the corresponding principal is read from the keytab. If the keytab got deleted adcli will try to identify an existing managed service account with the help of the fully-qualified name, if this fails a new managed service account will be created.

The managed service account password can be updated with

$ adcli update --domain=domain.example.com --host-keytab=/etc/krb5.keytab.domain.example.com

and the managed service account can be deleted with

$ adcli delete-computer --domain=domain.example.com 'myhost!A2c'

In addition to the global options, you can specify the following options to control how this operation is done.

-N, --computer-name=computer

-O, --domain-ou=OU=xxx

-H, --host-fqdn=host

-K, --host-keytab=/path/to/keytab

--show-details

--show-password

DELEGATED PERMISSIONS

When using an account with delegated permissions with adcli basically the same applies as well. However some aspects are explained here in a bit more details to better illustrate different concepts of Active Directory and to make it more easy to debug permissions issues during the join. Please note that the following is not specific to adcli but applies to all applications which would like to modify certain properties or objects in Active Directory with an account with limited permissions.

First, as said in the blog post it is sufficient to have "Create computer object" permissions to join a computer to a domain. But this would only work as expected if the computer object does not exist in Active Directory before the join. Because only when a new object is created Active Directory does not apply additional permission checks on the attributes of the new computer object. This means the delegated user can add any kind of attribute with any value to a new computer object also long as they meet general constraints like e.g. that the attribute must be defined in the schema and is allowed in a objectclass of the object, the value must match the syntax defined in the schema or that the sAMAccountName must be unique in the domain.

If you want to use the account with delegated permission to remove computer objects in Active Directory (adcli delete-computer) you should of course make sure that the account has "Delete computer object" permissions.

If the computer object already exists the "Create computer object" permission does not apply anymore since now an existing object must be modified. Now permissions on the individual attributes are needed. e.g. "Read and write Account Restrictions" or "Reset Password". For some attributes Active Directory has two types of permissions the plain "Read and Write" permissions and the "Validated Write" permissions. For the latter case there are two specific permissions relevant for adcli, namely

Details about the validation of the values can be found in the "Validated Writes" section of [MS-ADTS], especially dNSHostName[2] and servicePrincipalName[3]. To cut it short for "Validated write to DNS host name" the domain part of the fully-qualified hostname must either match the domain name of the domain you want to join to or must be listed in the msDS-AllowedDNSSuffixes attribute. And for "Validated write to service principal name" the hostname part of the service principal name must match the name stored in dNSHostName or some other attributes which are not handled by adcli. This also means that dNSHostName cannot be empty or only contain a short name if the service principal name should contain a fully-qualified name.

To summarize, if you only have validated write permissions you should make sure the domain part of the hostname matches the domain you want to join or use the --host-fqdn with a matching name.

The plain read write permissions do not run additional validations but the attribute values must still be in agreement with the general constraints mentioned above. If the computer object already exists adcli might need the following permissions which are also needed by Windows clients to modify existing attributes:

additionally adcli needs

This is added for security reasons to avoid that Active Directory stores Kerberos keys with (potentially weaker) encryption types than the client supports since Active Directory is often configured to still support older (weaker) encryption types for compatibility reasons.

All other attributes are only set or modified on demand, i.e. adcli must be called with an option the would set or modify the given attribute. In the following the attributes adcli can modify together with the required permissions are listed:

For the management of users and groups (adcli create-user, adcli delete-user, adcli create-group, adcli delete-group) the same applies only for different types of objects, i.e. users and groups. Since currently adcli only supports the creation and the removal of user and group objects it is sufficient to have the "Create/Delete User objects" and "Create/Delete Group objects" permissions.

If you want to manage group members as well (adcli add-member, adcli remove-member) "Read/Write Members" permissions are needed as well.

Depending on the version of Active Directory the "Delegation of Control Wizard" might offer some shortcuts for common task like e.g.

The first 2 shortcuts will provided full access to user and group objects which, as explained above, is more than currently is needed. After using those shortcut it is a good idea to verify in the "Security" tab in the "Properties" of the related Active Directory container that the assigned permissions meet the expectations.

BUGS

SEE ALSO

Further details available in the realmd online documentation at http://www.freedesktop.org/software/realmd/

NOTES

1.

Who can add workstation to the domain

2.

dNSHostName

3.

servicePrincipalName