.. warning:: The method of accessing the system may change in the future. The documentation will be updated as soon as possible. Client Installation ===================== In AFS the authentication is based on Kerberos protocol. A user can operate if he owns a “Kerberos Ticket” proving his identity. The ticket is created by the Kerberos client by contacting the Kerberos servers (Key Distribution Center - KDC) when the user provides the proper combination of userid/password. ENEAGRID has several KDC distributed between its sites. Historically AFS has used the Kerberos 4 implementation as a native part of its software package but it has been superseeded by the more robust Kerberos 5, in production in ENEAGRID since 2011. If a user wants to install OpenAFS on his workstation he must also install Kerberos 5 and configurate properly for his operating system. Instructions are provided for Windows, Linux and Mac. Download configuration ------------------------ The configuration **krb5.conf** file, with different version optimized for some of the main ENEA site (ENEAGRID credential required): - :download:`Casaccia `. - :download:`Frascati `. - :download:`Portici `. .. tabs:: .. tab:: LINUX The following sections provides the instructions for Ubuntu and Almalinux9. In all cases selinux should be disabled. In 2023 a set of rpm repositories for OpenAFS 1.8.8 (and later) has been made available by `Sinenomine `_. By using the instructions of the site is it possibile to install the openafs-client just by using yum/dnf after the local repository configuration. .. note:: The OpenAFS Guardians are happy to announce the availability of OpenAFS 1.8.7. Source files can be accessed via the web at: https://www.openafs.org/release/openafs-1.8.7.html or via AFS at: UNIX: /afs/grand.central.org/software/openafs/1.8.7/ UNC: \\afs\grand.central.org\software\openafs\1.8.7\ This release fixes a critical issue with the generation of Rx connection IDs (CIDs) for Rx clients started after 14 Jan 2021 08:25:36 AM UTC (Unix epoch time 0x60000000). Unpatched systems will always use the fixed value of 0x80000002 as the CID, which causes connections to fail for multiple reasons. Client commands such as `vos examine` will time out if run after that time, cache managers started after that time will be unable to access files, fileservers started after that time will be unable to access the Ubik databases, and database servers started after that time will be unable to participate in a quorum or Ubik elections. In particular, fileservers that restart, including due to a scheduled weekly restart, will not be able to register with the volume location service or verify group membership with the protection service. The fix causes the initial CID to be randomly generated (without dependence on the current time) and removes the faulty logic intended to detect signed integer overflow (which is not needed since the field in question is now an unsigned integer). **Ubuntu 18.04 LTS, 20.04 LTS** On Ubuntu (and derivatives) Kerberos 5 and OpenAFS packets are available in the standard repositories, so the installation of the OpenAFS and Kerberos 5 is straightforward. Sme configuration data must be provided by the user during the installation procedure. Here is the procedure from a root session (or using sudo): 1. Download krb5.conf for the selected site and copy it in root home 2. ``apt install krb5-user`` - Default kerberos version 5 realm: > ``ENEA.IT`` - Kerberos servers for your realm: aixfs.frascati.enea.it - Administrative server for your Kerberos real: afskdc.frascati.enea.it 3. ``mv /etc/krb5.conf /etc/krb5.conf_dist`` 4. ``mv ~/krb5.conf /etc/krb5.conf`` 5. ``apt install openafs-client openafs-krb5`` - AFS cell this workstation belongs to: enea.it - Size of AFS cache in kB: 500000 6. ``systemctl start openafs-client`` ; ``systemctl enable openafs-client`` 7. ``df `` The service configuration files are: **/etc/openafs/afs.conf.client /etc/openafs/afs.conf** .. note:: the bug in 1.8.x versions has been solved by the patch provided by this `link `_ by the following commands ``add-apt-repository ppa:openafs/stable`` ``apt upgrade`` **RH9.x, Almalinux 9.x** Also for RH9.x and Almalinux 9.x the OpenAFS rpms are not available on repositories so they must be rebuilt for the specific kernel version. It must be noted that OpenAFS 1.8.10 is required for RH 9.x and its derivatives so a script has been prepared for the OpenAFS client installation for version 1.8.10. The script is based on the instructions from this `link `_ 1. Download and run this :download:`compile_install_OpenAFS1810_RH9_v1.sh `. 2. Configure the AFS cell editing /usr/vice/etc/ThisCell: - ``echo "enea.it" >/usr/vice/etc/ThisCell`` 3. Start the service: ``systemctl start openafs-client`` 4. Download **krb5.conf** for the selected site and copy it in root home 5. ``dnf install krb5-workstation`` 6. ``mv /etc/krb5.conf /etc/krb5.conf_dist`` 7. ``mv ~/krb5.conf /etc/krb5.conf`` **Getting Ticket and token for enea.it AFS cell** To get a Kerberos 5 ticket and an AFS tokens for an ENEAGRID user: .. code-block:: bash kinit @ENEA.IT # @ENEA.IT can be omitted, as the defaut realm defined in the krb5.conf file. aklog # create a token klist; tokens # to verify the obtained ticket & token With the switch ``-d`` the comamnd ``aklog -d`` provides more information and it is useful to debug problems. .. note:: it is also possible to obtain a ticket and a tokens on AFS cell fusione.it, for users defined in the FUSIONE.IT realm: .. code-block:: bash kinit @FUSIONE.IT aklog -c fusione.it -k FUSIONE.IT **Passwordless ssh connection to an ENEAGRID node** When kerberos 5 has been properly configured it is possibile too acquire a Kerberos 5 ticket in the local system and use it to open a remote ssh session to an ENEAGRID node without having to provide the password. The local ssh client configuration file /etc/ssh/ssh_config must be configured as following: .. code-block:: bash GSSAPIAuthentication yes GSSAPIDelegateCredentials yes **How to verify the type of AFS token: user based or PAG based?** If a Kerberos 5 ticket is available the command aklog creates an AFS token based on the information in the ticket by contacting the AFS DB servers. Then there are two possibilities: 1. **user based AFS token** : the token is available to all the user processes on the node 2. **PAG based AFS token** : the token are available only in the current process and in its childrens. If aklog is called in the main ssh shell process the token is avalable to all the session processes but not to other ssh session of the same user [ PAG - Process Authentication Group ]. It is clear that on a multisession node a user based token can result in unexpected results as the command "unlog" deletes the token to all the user processes independently from how they were generated. The command ``keyctl show`` permits to verify if the current shell has a user or a PAG based token. For a user based token, root id=0 in this case: .. code-block:: bash Session Keyring 107061358 --alswrv 0 0 keyring: _ses 556891430 --alswrv 0 65534 \_ keyring: _uid.0 For a PAG based token: .. code-block:: bash Session Keyring -3 --alswrv 0 0 keyring: _ses.3347 647522168 ----s--v 0 0 \_ afs_pag: _pag .. tab:: MAC OS The raccomended AFS client fo MacOS X is now the Auristor client, available for all the latest MacOSX releases and compatible both with OpenAFS and Auristor file system. So start by dowloading the installation dmg packet from this `link `_ Current versions of MacOSX support natively Kerberos 5 MIT and the configuration file must have the name edu.mit.Kerberos. The file must be placed or in the root directory **/Library/Preferences/** or in the user HOME directory **~/Library/Preferences/**. Download krb5.conf for the selected site. The downloaded file has the suffix .txt that must be removed so that the file name is just **edu.mit.Kerberos**. At this point double-click on the downloaded Auristor dmg packet icon and then on the Auristor-Lite.pkg icon. Authenticate as admin user and select as usually the "Continue" tabs. When required provide **the local cell name "enea.it"** and proceed in the installation phase. When completed either reboot the Mac or open System Preferences, click Auristor pane and click "Start". The configuration files of the Auristor client are in the directory **/etc/yfs**. **Getting Ticket and token for enea.it AFS cell** To get a Kerberos 5 ticket and an AFS tokens for an ENEAGRID user: .. code-block:: bash kinit @ENEA.IT # @ENEA.IT can be omitted, as the defaut realm defined in the krb5.conf file. aklog # create a token klist; tokens # to verify the obtained ticket & token .. note:: It has been noticed that aklog provides the token after a long delay ( 30 s or more ) for enea.it AFS cell. This delay can be reduced substantially if the file /etc/yfs/cellservdb.conf is edited to reduce the number of referenced ENEA dbservers, according to the site where the user is located. The most reliable solution is to keep only the Frascati dbservers expecially for client outside ENEA network. A copy of the Frascati :download:`cellservdb.conf ` file can be downloaded here. A reboot is required after having modified the file. .. note:: it is also possible to obtain a ticket and a tokens on AFS cell fusione.it, for users defined in the FUSIONE.IT realm: .. code-block:: bash kinit @FUSIONE.IT aklog -c fusione.it -k FUSIONE.IT **Passwordless ssh connection to an ENEAGRID node** When kerberos 5 has been properly configured it is possibile too acquire a Kerberos 5 ticket in the local system and use it to open a remote ssh session to an ENEAGRID node without having to provide the password. The local ssh client configuration file /private/etc/ssh/ssh_config must be configured as following: .. code-block:: bash GSSAPIAuthentication yes GSSAPIDelegateCredentials yes **How to verify the type of AFS token: user based or PAG based?** In MacOSx al tokens are user based, so all the user processes share the same token. .. tab:: WINDOWS The software packages are: - Kerberos: the Heimdal implementation of Kerberos 5 protocol [`Heimdal site `_] - Network Identity Manager: a GUI application for Kerberos Ticket & AFS token [ `NIM site `_] - OpenAFS client: the OpenAFS client packed by Auristor [`Auristor site `_] .. note:: For simplicity a set of these packages is available here: :download:`yfs-openafs ` | :download:`netidmgr-heimdal ` | :download:`Heimdal ` **Installation steps** An administrator user should go through the following steps in the given order : 1. Download the packages and the configuration file. 2. Install Heimdal Kerberos for Windows. 3. Change the default configuration file C:\ProgramData\Kerberos5\krb5.conf with the one specific for ENEAGRID. 4. System reboot. 5. Install Network Identity Manager. 6. System reboot. 7. Install OpenAFS client, with all default values, but specifying the enea.it as the Default Cell. 8. System reboot. **Getting Ticket and token for enea.it AFS cell** To get a Kerberos Ticket and AFS tokens, follow these steps: 1. Click Start and select Network Identity Manager 2. Select the option "Credentials" and choose "New Credentials -> Obtain new credentials" and provide the ENEAGRID userid as the Username 3. In the following window the Lifetime of the Ticket/Token can be modified (The default is 10 hours, but a several days lifetime is surely acceptable.) 4. Select again the option option "Credentials" and choose "New Credentials -> Obtain new credentials" and provide the password. 5. If successful the main window of Network Identity Manager at this point will show the new active ticket/token information. The Kerberos ticket and the AFS token can also be obtained from the command line by issuing the commands: .. code-block:: bash kinit @ENEA.IT # @ENEA.IT can be omitted, as the defaut realm defined in the krb5.conf file. aklog # create a token klist; tokens # to verify the obtained ticket & token .. note:: There are cases where the application "Network Identity Manager" does not work properly and so the command line approach is the alternative solution. The command line prompt in WIndows 10 can be accessed with WindowsKey+X selecting "Command Prompt" option. **Mapping an AFS directory as a Windows Network Drive** To map an AFS directory as a Windows network Drive, you will need to open the File Explorer, for example by clicking the folder icon in the Taskbar. On the File Explorer windows, select "This PC" and the "Computer" Tab. Select "Connect to a Network Drive". In the resulting menu, provide the root path of the enea.it AFS cell in the format \\afs\enea.it (take care that the separator in the path is the backslash) and navigate to find the desired folder. **A note about C:\ProgramData folder** With default Windows 10 settings, folders as C:\ProgramData are hidden folders. To access it, you will need to change the defaults, opening the File Explorer, for example by clicking the folder icon in the Taskbar. On the File Explorer window select View, select Options and find the "folder options" dialog. Select the View Tab and switch on the radio button "Show Hidden Files, Folders and Drives". You should now be able to see and access the "C:\Program Data" folder. Of course default Windows 10 configuration can be restored later, after the application of the desired modification.