cid-doc.github.io

CID

License: GPLv3

Homepage Discussion Donations Changelog

Contents

Description

CID (Closed In Directory) is a set of bash scripts for inserting and managing Linux computers in Active Directory (AD) domains. Modifications made to the system allow Linux to behave like a Windows computer within AD.

You can do things like:

CID consists of four main tools subdivided into two GUI tools (cid-gtk and cid-change-pass-gtk) and two CLI utilities (cid and cid-change-pass). Both pairs contain equivalent features and they all accept the following general options as a argument in the command line:

Options Description
-v, –version Show the version
-h, –help Show the help

Requirements

Installation

Ubuntu 

$ sudo add-apt-repository ppa:emoraes25/cid
$ sudo apt update
$ sudo apt install cid cid-gtk

Debian 

$ [ -d /etc/apt/keyrings ] || sudo mkdir -m0755 -p /etc/apt/keyrings
$ sudo wget -O /etc/apt/keyrings/cid-archive-keyring.pgp https://c-i-d.sourceforge.io/keys/cid-archive-keyring.pgp
$ sudo wget -O /etc/apt/sources.list.d/cid.sources https://c-i-d.sourceforge.io/repo/apt/debian/cid.sources
$ sudo apt update
$ sudo apt install cid cid-gtk

Fedora 

$ sudo rpm --import https://c-i-d.sourceforge.io/keys/CID-GPG-KEY
$ sudo dnf config-manager --add-repo https://c-i-d.sourceforge.io/repo/rpm/cid.repo
$ sudo dnf install cid

OpenSUSE 

$ sudo rpm --import https://c-i-d.sourceforge.io/keys/CID-GPG-KEY
$ sudo zypper ar https://c-i-d.sourceforge.io/repo/rpm/cid.repo
$ sudo zypper in cid

Other distros

After installing the requirements, download the tarball, unzip it and run as root the INSTALL.sh script. You can use the following commands:

$ ver='x.x.x' #current version
$ wget https://downloads.sf.net/c-i-d/files/cid-${ver}.tar.gz    
$ tar -xzf cid-${ver}.tar.gz
$ cd cid-${ver}
$ sudo ./INSTALL.sh

Note: Run sudo ./INSTALL.sh uninstall to uninstall the program files from the same version of the package.

cid-gtk

The cid-gtk is the tool that contains the main features of the program. Through it you can insert your Linux computer in an AD domain and later manage a series of functions in the system.

The available features are described in the following sections.

Join the domain

This function allows you to join the Linux computer to an AD domain. For that, it is necessary to inform the domain data in the respective fields as shown in the table below:

Field Description
Domain Domain name (FQDN).
Hostname Name for computer account that will be created in AD. If not specified, the account will be created with the same hostname defined in the system.
Organizational Unit Optionally, you can specify an Organizational Unit where the computer account will must be created when join it the domain. If the OU is not entered or is not found, the computer account will be created in the default container (computers).
User Domain administrator user.
Password User password.
Mode Select one of two join modes: Default or Advanced. Default mode is adopted if no selection is made. Advanced mode opens a form that allows you to customize the settings that the CID will perform on the system during the process of joining the domain. All configuration options available in this mode are directly opposite to the settings adopted in the Default mode.

Note: Before modifying the system files, the CID makes a backup in the /var/lib/cid/backups/ori directory.

Advanced mode

The options available in this mode are:

Option Description
Disable NetBIOS over TCP/IP Disables support for the NetBIOS API implemented by Samba.
Disable authentication via Kerberos This causes the pam_winbind module to not attempt to obtain the kerberos tickets known as Ticket Granting Tickets (TGTs) of the Authentication Server (AS) during user login.
Disable credential caching Disables support for off-line authentication, or authentication with local cached credentials. This requires real-time communication with the authentication server for the logins the domain users.
Disable logon scripts This disables logon scripts.
Do not use domain as default Configures winbind not to use the joined domain as the system default. This makes it necessary to specify the domain name before the user or group name (format: DOMAIN\user or DOMAIN\group), both in authentication and in system commands that receive user or group names as argument.
Enable authentication for sudo This requires that domain users who are given administrative privileges on the Linux computer need to authenticate when running the sudo command (see Manage AD accounts in local groups).
Use idmap_ad (RFC 2307) This option allows the use of the idmap_ad backend, which implements an API to obtain the Unix attributes of users and groups in the domain through domain controllers, as long as they have NIS extensions enabled. By default, the CID configures winbind to use the idmap_autorid backend, which establishes these attributes through a predefined configuration on the local system. You can use the id_range_size, max_num_domains, wbd_userprofile and wbd_usershell parameters in cid.conf to customize this configuration. When selecting this option, a new form will be presented for configuring the backend with the following fields:

- Initial ID: Initial value of the range of UIDs and GIDs that will be mapped by the backend. This field is required, and the value assigned must be greater than the IDs already used by local users and groups;

- Final ID: End value of the range of UIDs and GIDs that will be mapped by the backend. When not set, the CID will use a random value based on the value set in the Initial ID field;

- winbind nss info: This defines whether information about the home directory and the shell of domain users should also be obtained by the DC with the rfc2307 option, or whether through a predefined configuration with the template option. The template option is adopted by default.
Share all printers on CUPS Enables automatic sharing of all printers configured on the local CUPS server through Samba (SMB protocol). This makes it unnecessary to configure individual shares for each printer through the Manage shares option.
Use keytab file method Configures Samba to use a dedicated keytab file as an kerberos authentication method. The krb_principal_names parameter in the cid.conf file can be used to specify principal names that you want to be added to the keytab.
Add config file to Samba It allows adding a file containing parameters to be attached to the Global section of the samba configuration file (smb.conf). The contents of this file will be filtered so that there is no conflict with the parameters predefined by the CID.

Remove from domain

This function undoes the modifications made in the system for the computer to join the domain, and by the use of the other CID functionalities after that join.

When using it, you can optionally fill in the fields with the credentials of a domain administrator for what the CID try remotely delete the computer account from the AD database. If this fails, the operation of this function will not be affected.

Note: A copy of the files modified during this process is stored in the /var/lib/cid/backups/mod directory.

Change station behavior

This function allows you to change the options of the Advanced mode after the system joins an AD domain.

Note: Whenever a change is made through this função, a copy of the affected files in the state before modification is stored in the /var/lib/cid/backups/mod directory.

Block logon

This function restricts logon in the system to a specific user or group of the domain. When selecting it you must inform the Account Type (User or Group) and the Account Name. If no type is selected, the User type is assumed by default.

Unblock logon

This function removes the logon restriction applied by the block logon function.

Manage AD accounts in local groups

This function allows you to associate AD user accounts with groups on the local system so that they can perform specific routines that require the administrative privileges of those groups, in addition to allowing them to run the sudo command.

Authentication for the sudo command can be enabled or disabled via the Enable authentication for "sudo" option in advanced join mode or in Change station behavior.

The CID uses the groups that the default user (usually the first user created on the system) belongs to to determine these groups. You can specify any other user using the defaultuserid parameter, and you can also add other specific groups using the localgroups parameter in the cid.conf file.

In the Add account option, you must inform the type and name of the account in the same way as when using the block logon function.

Note that on Unix systems there is no group nesting. Therefore, when a group account is added, members of that group are individually associated to the local groups as they log on to this system. If you enter an asterisk (*) at the end of the group’s name, all its members will be immediately associated. If the user is removed from the domain group, the user will be automatically removed from local groups on a next login to this computer.

The Remove account option lists domain accounts added to local groups and allows you to select them for removal.

Note: Members of the Domain Admins group are automatically associated with local groups.

Manage shares

This function allows you to manage Samba shares intuitively.

The Add share option displays a form where you must enter the arguments to create or update a share.

Three share modes are available:

Common mode

This mode allows you to share a directory on one of the local file systems via Samba (SMB protocol).

The directory path to be shared must be entered in the Path argument. If the directory path does not start with a forward slash (/) and you are using a template for the share, the parent directory of the template share is used as the parent directory for this share. If the directory does not exist, it will be created automatically.

The access permissions of the share can be managed locally through the Rule argument, or through a remote Windows system using the Microsoft Management Console (MMC).

When set locally, permissions are translated into extended POSIX ACLs and interpreted by Samba as Windows ACLs. They must be composed of 03 fields separated by colons (:) and have the format [Type]:Account:[Permission], where:

Other important aspects about permissions are:

Some examples:

Allowing full access to the Domain Users group
g:domain users:f
Adding read-only permission to the Guest user account
+u:guest:r
Removing permissions for the Guest user account
-u:guest
Allowing full access to all users and denying access to the Guests group
u:everyone:f;g:guests:d

Userfolder mode

This mode enables the homes section of Samba, which is a special type of file sharing that automatically provides a share with the same name as the user who accesses it. In this mode, the Path argument must contain the path of the parent directory where the diretories for each user are to be created. If this argument is omitted, the /home directory will be assumed by default. CID automatically creates user directories with appropriate permissions as users first access their respective shares. If disk quota is used, it will be automatically applied to each user directory.

Printer mode

Mode used to share a printer configured on the local CUPS server through Samba (SMB protocol). This is optional or unnecessary when the Share all printers on CUPS option (see Advanced mode) is enabled. In this mode, the Path argument must receive the name of a configured printer in CUPS instead of a directory path. If left blank, this argument will receive the value used in the Name argument or vice versa. When printer sharing is enabled, a special file share called print$ will be configured to automatically provide shared printer drivers to Windows clients on the network. The location of the directory to be used for this share can be adjusted using the prtdrvdir parameter in the cid.conf file. Driver files must be manually copied to this directory or you must use a Windows system utility to manage the drivers on that print server (visit this link for more information).

Here is the complete list of arguments for a share:

Argument Description
Mode Share mode. Common mode is adopted if no selection is made.
Name Name of a new share or share to be updated. In an update it is only necessary to fill in the fields that will be changed.
Template Select a template for the share. The properties of the template will be copied to the share, except those that are specified. The Template argument can also be used to select a share to update, if the Name argument is left blank. Userfolder mode does not support this argument.
Path Directory path or CUPS printer name.
Rule Use this argument to manage share permissions in Common mode.
Comment Provides a description for the share. This is optional.
Disk Quota Size Disk quota applied to the shared directory in the Common and Userfolder share modes. Use the letter k, m, g, t, p, e, z or y after an integer to indicate a unit (kilobytes, megabytes, gigabytes …). If the unit is omitted, k (kilobytes) is adopted by default. Use the zero (0) number in this field to remove a disk quota previously applied to the share. The quota feature is currently only available for shared directories on XFS file systems.
Tolerance Quota Size Size of the tolerance quota that will be temporarily allowed when the disk quota is reached. The tolerance quota is optional and can only be used during the period determined by the qttltime parameter in cid.conf. After this period, the shared directory will not be able to write any more files until the use of its disk space is reduced to a value lower than the one defined in the Disk Quota Size. Use the letter k, m, g, t, p, e, z or y after an integer to indicate a unit (kilobytes, megabytes, gigabytes…). If the unit is omitted, k (kilobytes) is adopted by default. Use the zero (0) number in this field to remove a tolerance quota previously applied to the share. The quota feature is currently available only for directories shared on XFS file systems.
Apply Quota to Fst-level of Subdirs In Common mode it applies the disk quota and tolerance quota (if defined) to the first level subdirectories instead of the shared directory. This is the default behavior for Userfolder mode.
Hidden If set to Yes, hides the share of the list of available shares in the net view and browse list. The default value is No.
Allow Guest If set to Yes, allows the share to be accessed without authentication (no password) by any user. The default value is No.
Add Config File It allows adding a file containing parameters to be attached to the section of the share in the Samba configuration file (smb.conf). The contents of this file will be filtered so that there is no conflict with the parameters predefined by CID.

The Remove share option displays the shares added by the tool and allows you to select them for deletion.

When you delete a share from Common mode, Extended POSIX ACLs are reset recursively on the file system. The user directories created by the Userfolder share mode, on the other hand, will not have their properties changed.

When you delete a share of the Printer mode, only the configuration in Samba is removed. The configuration of the printer on the CUPS server is not affected.

Help

This function provides the following support options of the program:

Option Description
About CID Displays general information about the program.
Station info This option displays the status of the settings made on the system after join a domain.
App log This displays the log generated by the program’s functions on the current day. The complete log can be consulted in /var/log/cid/functions.log.
Scripts log This displays the log generated by the logon scripts on the current day. The complete log can be consulted in /var/log/cid/scripts.log.

Note: The rows number of the log files can be adjusted by the logsize parameter in cid.conf file.

cid

The cid is the CLI alternative to cid-gtk, and can be used to run all the features of the graphical tool on the command line or in bash scripts.

Note: Use man cid command to access the complete manual for that utility.

cid-change-pass and cid-change-pass-gtk

The cid-change-pass is a command line utility that allows domain users to change their passwords directly from the Linux computer joined to AD.

The command must be executed by the user himself who wants to change his password. It must inform the program of its current password and the new password. This may contain restrictions according to the domain’s security policies.

If run as a superuser (root), the program should receive one or more domain user accounts as an argument. You will need to enter the current password for each of these users to perform the password change procedure.

The cid-change-pass-gtk tool provides a simple and intuitive graphical interface to the cid-change-pass utility.

cid.conf

The cid.conf is a configuration file installed in the /etc/cid directory which allows you to adjust the values of the variables used in the CID scripts adapting its operation to the Linux environment to which it was installed.

The parameters in this file are declared as bash variables in the following format:

parameter=value

Note that there should be no spaces between the equal sign (=) that separates the parameter from its corresponding value. Some parameters admit more than one value, and in these cases, the values must be separated by a single space, but between single quotes (‘) or double quotes (“), which are mandatory if environment variables are used in the value of a parameter.

Lines that start with a hashtag (#) are just comments and are not interpreted by the program. The original file of the package contains all accepted parameters accompanied by comments that describe them widely. You can access a copy of this file at this link.

Note: Modifications made to the file after the system has already been joined to a domain will only be applied if you reload the CID Init Script with the command: systemctl reload cid.

CID Init Script

The CID Init Script is a Unit file for Systemd generated when the computer joins the domain and is responsible for maintaining the settings made by the CID and also for making other adjustments during system initialization, such as forcing time synchronization with the domain controllers and update the /etc/hosts file (useful in DHCP-based networks).

You can manually force reconfiguration of files modified by the CID using the command: systemctl reload cid. This will also cause the changes made to the cid.conf file after the system joins the domain to will be applied.

The CID Init Script is a unit file of the oneshot type and does not keep active processes as a common service after the system initialization.

Note: When removing the computer from the domain the CID Init Script is also removed.

Logon scripts

The CID can configure the Linux computer to allow bash scripts stored on the Netlogon share to run when domain users logon.

Basically the process consists of mounting the Netlogon on local file system, and then executed the scripts in the system shell. In the end, Netlogon is unmounted again. All of this is done automatically and transparently to the user.

If the Disable logon scripts option is not enabled (see Advanced mode), during the system joining the domain, and if it does not already exist, the CID tries to export to Netlogon a template of this scripts using the credentials of the domain administrator user used to the join. This files is provided with the program’s source package and is installed in the /usr/share/cid/templates directory. See the details about the scripts in the next subsections!

Note: The scripts were stored in the scripts_cid folder in Netlogon. As of version 1.2.5 this folder has been renamed to cid only!

logon.sh and logon_root.sh

The logon_root.sh is the bash script executed with the root user UID, which grants privileges for the execution of routines that require the powers of the superuser. It is executed before logon.sh.

The logon.sh is the bash script executed with the UID of the user who is logging in and can be used to execute routines that do not require elevated privileges. It is executed after logon_root.sh.

In both scripts, in addition to the known bash variables, you can use the following environment variables exported by the CID:

Variable Description
NETLOGON Mount point of the Netlogon share on the system.
USERNAME Name of the user that are opening session.
USERID ID of the user that are opening session.
USERDOMAIN Domain name of the user that is opening session.
USERPROFILE Home directory path of the user that is opening session.
USERSHELL Login shell of the user that is opening session.
GROUPID Primary group ID of the user that is opening session.
USERGROUP Primary group name of the user that is opening session.
USERGROUPS Group list separated by commas (,) of the user that is opening session.

Automatic mounting of shared folders

The automatic mounting of shared folders during users logon can be performed through the pam_mount module.

Pam_mount is a library that allows you to mount a file system transparently through PAM authentication. In general, the file systems to be mounted are defined in your global configuration file (usually /etc/security/pam_mount.conf.xml). The shares.xml file is nothing more than a copy of this file stored on Netlogon, which replaces the original configuration file on Linux computers of the domain during users logon. In this way, all configuration can be centralized in this single file to be applied to all theses computers.

The file systems to be mounted are defined in <volume ...> tags. The default shares.xml file contains some examples of defining common SMB shares, such as:

<!-- Mounting the 'public' share -->
<volume fstype="cifs" server="fileserver" path="public" mountpoint="~/public" />

<!-- Mounting the user's network folder -->
<volume fstype="cifs" server="fileserver" path="%(USER)" mountpoint="~/MyNetFolder" />

<!-- Mounting the 'IT$' share for 'ITD' group users -->
<volume sgrp="itd" fstype="cifs" server="fileserver" path="it$" mountpoint="~/IT" />

<!-- Mounting the 'HR' share for users in the 'HRD' group of the 'SAMPLE' trusted domain -->
<volume sgrp="SAMPLE\hrd" fstype="cifs" server="fileserver" path="hr$" mountpoint="~/HR" options="domain=SAMPLE" />

<!-- Mounting the 'cameras' share for users in the 'security' or 'monitors' group of the 'example.com' domain -->
<volume fstype="cifs" server="fileserver" path="cameras" mountpoint="~/cameras" options="domain=example.com">
	<or>
		<sgrp>security</sgrp>
		<sgrp>monitors</sgrp>
	</or>
</volume>

See the pam_mount documentation for more information on its configuration.

Automatic configuration of printers

One way to automate printers setup is to use the lpadmin utility in logon scripts.

Lpadmin is a command line utility that configures printers or print classes for CUPS. With it, you can easily add, remove or even set a printer as a default on the Linux system.

Generally, printer management is only allowed for the root user or users who are members of the CUPS management group, whose name may vary from one Linux distribution to another. For this reason, definitions of printers mapping should normally be made in the logon_root.sh script.

# Eg: Adding printer to the system
lpadmin -p printer -E -v ipp://printer_address/ipp/printer -m everywhere

Troubleshooting

This section describes known cases related to the program.

Graphic Mode Login Managers

In certain Linux distributions, some login managers in their default configuration do not list users who are in a remote source and/or do not have options so that the credentials of those users can be informed through a prompt or text box. In such cases you should consult the manual of your distribution or of the login manager in question to see if these options are available and what settings should be made. If necessary, install a new graphical login manager.

Failed to join machines to .local domains

It is common to get an error when joining the machine in domains with the .local top-level domain (TLD). This is because the .local domain was reserved for applications that use DNS Multicast (mDNS) to provide zero-configuration networks (zeroconf). On linux, Avahi is an example of these applications. Generally, mDNS resolution is prioritized over Unicast DNS resolution, which prevents querying by domain controllers (DCs) from reaching the domain’s DNS servers. A way around this is to associate the IP address of one of the DCs with the domain name in the /etc/hosts file, for example:

echo -e "192.168.25.25\texample.local" | sudo tee -a /etc/hosts

Being:

Numeric users login failed

Since the systemd session manager stopped supporting user accounts whose login consists only of numbers (bug #15141), it has been a problem for AD administrators to make it possible to log on of accounts with this format on Linux computers integrated into AD, either through CID or other similar tools. Fortunately, there is an unusual way to resolve this issue!

In the CID, you can enable the Do not use domain as default option among the join options of the Advanced mode or the Change station behavior option, if the computer is already in AD. You can also use the --no-defaultdomain option along with the join subcommand on the command line (eg: cid join -p --no-defaultdomain). This will cause user accounts to be identified on the system with the format DOMAIN\username, which ensures that there are non-numeric characters as well. The bad part is that this implies in the user must always enter the domain along with the username to log on, either in the UPN format (username@fqdn) or in the low-level login name format itself (DOMAIN\username).


Release 1.2.5 2023-06-11
Copyright (C) 2012-2023 Eduardo Moraes «emoraes25@gmail.com»