Manage users

Defining users, groups, roles and permissions allows you to control who has access to your XenServer hosts and pools and what actions they can perform.

When you first install XenServer, a user account is added to XenServer automatically. This account is the local super user (LSU), or root, which XenServer authenticates locally.

The LSU, or root, is a special user account intended for system administration and has all permissions. In XenServer, the LSU is the default account at installation. XenServer authenticates the LSU account. LSU does not require any external authentication service. If an external authentication service fails, the LSU can still log in and manage the system. The LSU can always access the XenServer physical server through SSH.

You can create more users by adding the Active Directory accounts through either XenCenter’s Users tab or the xe CLI. If your environment does not use Active Directory, you are limited to the LSU account.

Note:

When you create users, XenServer does not assign newly created user accounts RBAC roles automatically. Therefore, these accounts do not have any access to the XenServer pool until you assign them a role.

These permissions are granted through roles, as discussed in the Authenticating users with Active Directory (AD) section.

Authenticate users with Active Directory (AD)

If you want to have multiple user accounts on a server or a pool, you must use Active Directory user accounts for authentication. AD accounts let XenServer users log on to a pool using their Windows domain credentials.

You can configure varying levels of access for specific users by enabling Active Directory authentication, adding user accounts, and assign roles to those accounts.

Active Directory users can use the xe CLI (passing appropriate -u and -pw arguments) and also connect to the host using XenCenter. Authentication is done on a per-resource pool basis.

Subjects control access to user accounts. A subject in XenServer maps to an entity on your directory server (either a user or a group). When you enable external authentication, XenServer checks the credentials used to create a session against the local root credentials (in case your directory server is unavailable) and then against the subject list. To permit access, create a subject entry for the person or group you want to grant access to. You can use XenCenter or the xe CLI to create a subject entry.

If you are familiar with XenCenter, note that the XenServer CLI uses slightly different terminology to refer to Active Directory and user account features: XenCenter Term XenServer CLI Term Users Subjects Add users Add subjects

Active Directory authentication in the XenServer environment

Even though XenServer is Linux-based, XenServer lets you use Active Directory accounts for XenServer user accounts. To do so, it passes Active Directory credentials to the Active Directory domain controller.

When you add Active Directory to XenServer, Active Directory users and groups become XenServer subjects. The subjects are referred to as users in XenCenter. Users/groups are authenticated by using Active Directory on logon when you register a subject with XenServer. Users and groups do not need to qualify their user name by using a domain name.

To qualify a user name, you must type the user name in Down-Level log on Name format, for example, mydomain\myuser.

Note:

By default, if you did not qualify the user name, XenCenter attempts to log in users to AD authentication servers using the domain to which it is joined. The exception to this is the LSU account, which XenCenter always authenticates locally (that is, on the XenServer) first.

The external authentication process works as follows:

  1. The credentials supplied when connecting to a server are passed to the Active Directory domain controller for authentication.

  2. The domain controller checks the credentials. If they are invalid, the authentication fails immediately.

  3. If the credentials are valid, the Active Directory controller is queried to get the subject identifier and group membership associated with the credentials.

  4. If the subject identifier matches the one stored in the XenServer, authentication succeeds.

When you join a domain, you enable Active Directory authentication for the pool. However, when a pool joins a domain, only users in that domain (or a domain with which it has trust relationships) can connect to the pool.

Note:

Manually updating the DNS configuration of a DHCP-configured network PIF is unsupported and can cause AD integration, and therefore user authentication, to fail or stop working.

Configure Active Directory authentication

XenServer supports use of Active Directory servers using Windows 2008 or later.

To authenticate Active Directory for XenServer hosts, you must use the same DNS server for both the Active Directory server (configured to allow for interoperability) and the XenServer host. In some configurations, the active directory server can provide the DNS itself. This can be achieved either using DHCP to provide the IP address and a list of DNS servers to the XenServer host. Alternatively, you can set the values in the PIF objects or use the installer when a manual static configuration is used.

Citrix recommends enabling DHCP to broadcast host names. Do not assign the hostnames localhost or linux to hosts.

Warning:

XenServer host names must be unique throughout the XenServer deployment.

Note the following:

  • XenServer labels its AD entry on the AD database using its hostname. If two XenServer hosts with the same hostname are joined to the same AD domain, the second XenServer overwrites the AD entry of the first XenServer. The overwriting occurs regardless of whether the hosts belong to the same or different pools. This can cause the AD authentication on the first XenServer to stop working.

    You can use the same host name in two XenServer hosts, as long as they join different AD domains.

  • The XenServer hosts can be in different time-zones, because it is the UTC time that is compared. To ensure that synchronization is correct, you can use the same NTP servers for your XenServer pool and the Active Directory server.

  • Mixed-authentication pools are not supported. You cannot have a pool where some servers in the pool are configured to use Active Directory and some are not).

  • The XenServer Active Directory integration uses the Kerberos protocol to communicate with the Active Directory servers. Therefore, XenServer does not support communicating with Active Directory servers that do not use Kerberos.

  • For external authentication using Active Directory to be successful, clocks on your XenServer hosts must be synchronized with the clocks on your Active Directory server. When XenServer joins the Active Directory domain, the synchronization is checked and authentication fails if there is too much skew between the servers.

Warning:

Host names must consist solely of no more than 63 alphanumeric characters, and must not be purely numeric.

When you add a server to a pool after enabling Active Directory authentication, you are prompted to configure Active Directory on the server joining the pool. When prompted for credentials on the joining server, type Active Directory credentials with sufficient privileges to add servers to that domain.

Active Directory integration

Ensure that the following firewall ports are open for outbound traffic in order for XenServer to access the domain controllers.

Port Protocol Use
53 UDP/TCP DNS
88 UDP/TCP Kerberos 5
123 UDP NTP
137 UDP NetBIOS Name Service
139 TCP NetBIOS Session (SMB)
389 UDP/TCP LDAP
445 TCP SMB over TCP
464 UDP/TCP Machine password changes
3268 TCP Global Catalog Search

Notes:

  • To view the firewall rules on a Linux computer using iptables, run the following command: iptables - nL.
  • XenServer uses PowerBroker Identity Services (PBIS) to authenticate the AD user in the AD server, and to encrypt communications with the AD server.

How does XenServer manage the machine account password for AD integration?

Similarly to Windows client machines, PBIS automatically updates the machine account password. PBIS renews the password every 30 days, or as specified in the machine account password renewal policy in the AD server.

Enable external authentication on a pool

External authentication using Active Directory can be configured using either XenCenter or the CLI using the following command.

xe pool-enable-external-auth auth-type=AD \
  service-name=full-qualified-domain \
  config:user=username \
  config:pass=password

The user specified must have Add/remove computer objects or workstations privilege, which is the default for domain administrators.

If you are not using DHCP on the network used by Active Directory and your XenServer hosts, use the following approaches to set up your DNS:

  1. Set up your domain DNS suffix search order for resolving non-FQDN entries:

      xe pif-param-set uuid=pif-uuid_in_the_dns_subnetwork \
      “other-config:domain=suffix1.com suffix2.com suffix3.com”
    
  2. Configure the DNS server to use on your XenServer hosts:

    xe pif-reconfigure-ip mode=static dns=dnshost ip=ip \
    gateway=gateway netmask=netmask uuid=uuid
    
  3. Manually set the management interface to use a PIF that is on the same network as your DNS server:

    xe host-management-reconfigure pif-uuid=pif_in_the_dns_subnetwork
    

Note:

External authentication is a per-host property. However, Citrix recommends that you enable and disable external authentication on a per-pool basis. A per-pool setting allows XenServer to deal with failures that occur when enabling authentication on a particular host. XenServer also rolls back any changes that may be required, ensuring a consistent configuration across the pool. Use the host-param-list command to inspect properties of a host and to determine the status of external authentication by checking the values of the relevant fields.

Use XenCenter to disable Active Directory authentication, or the following xe command:

xe pool-disable-external-auth

User authentication

To allow a user access to your XenServer host, you must add a subject for that user or a group that they are in. (Transitive group memberships are also checked in the normal way. For example, adding a subject for group A, where group A contains group B and user 1 is a member of group B would permit access to user 1.) If you want to manage user permissions in Active Directory, you can create a single group that you then add and delete users to/from. Alternatively, you can add and delete individual users from XenServer, or a combination of users and groups as appropriate for your authentication requirements. You can manage the subject list from XenCenter or using the CLI as described in the following section.

When authenticating a user, the credentials are first checked against the local root account, allowing you to recover a system whose AD server has failed. If the credentials (user name and password) do not match, then an authentication request is made to the AD server. If the authentication is successful, the user’s information is retrieved and validated against the local subject list. Access is denied if the authentication fails. Validation against the subject list succeeds if the user or a group in the transitive group membership of the user is in the subject list.

Note:

When using Active Directory groups to grant access for Pool Administrator users who require host ssh access, the number of users in the Active Directory group must not exceed 500.

To add an AD subject to XenServer:

xe subject-add subject-name=entity name

The entity name is the name of the user or group to which you want to grant access. You can include the domain of the entity (for example, ‘xendt\user1’ as opposed to ‘user1’) although the behavior is the same unless disambiguation is required.

Find the user’s subject identifier. The identifier is the user or the group containing the user. Removing a group removes access to all users in that group, provided they are not also specified in the subject list. Use the subject list command to find the user’s subject identifier. :

xe subject-list

This command returns a list of all users.

To apply a filter to the list, for example to find the subject identifier for a user user1 in the testad domain, use the following command:

xe subject-list other-config:subject-name='testad\user1'

Remove the user using the subject-remove command, passing in the subject identifier you learned in the previous step:

xe subject-remove subject-uuid=subject-uuid

You can end any current session this user has already authenticated. For more information, see Terminating all authenticated sessions using xe and Terminating individual user sessions using xe in the following section. If you do not end sessions, users with revoked permissions may continue to access the system until they log out.

Run the following command to identify the list of users and groups with permission to access your XenServer host or pool:

xe subject-list

Remove access for a user

When a user is authenticated, they can access the server until they end their session, or another user ends their session. Removing a user from the subject list, or removing them from a group that is in the subject list does not automatically revoke any already-authenticated sessions that the user has. Users can continue to access the pool using XenCenter or other API sessions that they have already created. XenCenter and the CLI provide facilities to end individual sessions, or all active sessions forcefully. See the XenCenter help for information on procedures using XenCenter, or the following section for procedures using the CLI.

Terminate all authenticated sessions using xe

Run the following CLI command to end all authenticated sessions using xe:

xe session-subject-identifier-logout-all

Terminate individual user sessions using xe

  1. Determine the subject identifier whose session you want to log out. Use either the session-subject-identifier-list or subject-list xe commands to find the subject identifier. The first command shows users who have sessions. The second command shows all users but can be filtered. For example, by using a command like xe subject-list other-config:subject-name=xendt\\user1. You may need a double-backslash as shown depending on your shell).

  2. Use the session-subject-logout command, passing the subject identifier you have determined in the previous step as a parameter, for example:

    xe session-subject-identifier-logout subject-identifier=subject-id
    

Leave an AD domain

Warning:

When you leave the domain (that is, disable Active Directory authentication and disconnect a pool or server from its domain), any users who authenticated to the pool or server with Active Directory credentials are disconnected.

Use XenCenter to leave an AD domain. See the XenCenter help for more information. Alternately run the pool-disable-external-auth command, specifying the pool uuid if necessary.

Note:

Leaving the domain does not delete the host objects from the AD database. For information on how to delete disabled host entries, see the Microsoft Support article.