.. _appendix-e:

########################
Appendix C - RLM Hostids
########################

.. include:: ../../general/hostids.rst

------

**********************
Linux Ethernet hostids
**********************

Some recent versions of linux have very high ethernet adapter numbers. RLM was updated to scan 
100,000 interfaces starting in v12.0, however, this scan was too slow for applications that made 
multiple calls to rlm_init(). Beginning in v12.2, this number was reduced to 5,000. However, we 
have been informed of Docker instances where the ethernet device number is between 14,000 and 
15,000. In v15.0, we have left the default scan at 5,000 devices, but added the environment variable
RLM_LINUX_ETHERNET_ITERATIONS to control how many devices are scanned. 

To scan more (or fewer) ethernet devices, set this variable as follows (this example sets the 
number to 20,000):

.. code-block::
	text
	:caption: From the shell

	% setenv RLM_LINUX_ETHERNET_ITERATIONS 20000

or

.. code-block::
	text
	:caption: In your application

	rlm_putenv(“RLM_LINUX_ETHERNET_ITERATIONS=20000”)

------

***************
Windows hostids
***************

Ethernet
========

Some interfaces on Windows systems have Ethernet MAC addresses which are undesirable for use as
hostids because they are transient, i.e. not always available. These include wireless interfaces, 
virtual interfaces like VPNs, etc.

On Windows, RLM looks for keywords in the device description to decide what interfaces are 
undesirable. Licenses can be locked to these interfaces if necessary, as it might be that only 
undesirable interfaces exist on a given machine. However, When RLM generates a list of MAC 
addresses on a Windows machine, it orders the list such that the undesirables are at the end of 
the list. So the first hostid printed by rlmhostid, and the one returned by *rlm_hostid()* will be 
the best one available on that Windows system.

disksn
======

Some disk serial numbers on Windows are only accessible to a process running with admin privileges. 
To disable use of disk serial numbers that only admins can use, see the call to
*rlm_isv_cfg_set_use_admin_disksns()* in rlm_isv_config.c".

------

*******************
Miscellaneous Notes
*******************

RLMID
=====

The RLMID series of hostids are optional products, and will often require other software to be
installed on the system on which they are to be used. For these devices, see :ref:`appendix-f`.

Wildcards
=========

IP address hostids can contain the wildcard ('*') character in any position to
indicate that any value is accepted in that position.

A wildcard may be used in the host type hostid, for example:

.. code-block::
	text

   "hostid=host=*.stanford.edu" or "hostid=host=*.reprisesoftware.com"

------

******************************
Disabling standard RLM Hostids
******************************

You can disable certain hostid types in your application in rlm_isv_config.c. 

.. note:: rlmsign will sign licenses with disabled hostid types. 

In your application, if this hostid type appears in a signed license file,
*rlm_checkout()* will return RLM_EL_NOTTHISHOST. Your license server will log lines similar to 
these (in this case, we disabled the HOST hostid type, RLM_DISABLE_H_HOST):

.. code-block::
	text

	06/14 14:44 (reprise) Wrong Hostid - licenses may not be available

	06/14 14:44 (reprise) (expected: host=zippy, we are: invalid)

To disable hostids, modify rlm_isv_config.c as follows:

* Set the hostids that your product (or license server) will **not** accept. 
* Create a bitmask of the hostid types you do **not** want to support, and pass this as the the 
  2nd parameter to rlm_isv_cfg_disable_hostids(). If this parameter is 0, all RLM hostids are 
  allowed.

For example, say that you want to disable HOST and USER hostid types:

.. code-block::
	text

	int disable = RLM_DISABLE_H_USER | RLM_DISABLE_H_HOST;
	rlm_isv_cfg_disable_hostids(handle, disable);

The bitmask values for disabling various hostid types are in license.h, and are here:

* RLM_DISABLE_H_32BIT
* RLM_DISABLE_H_STRING
* RLM_DISABLE_H_ETHER
* RLM_DISABLE_H_USER
* RLM_DISABLE_H_HOST
* RLM_DISABLE_H_IP
* RLM_DISABLE_H_ANY
* RLM_DISABLE_H_DEMO
* RLM_DISABLE_H_SN
* RLM_DISABLE_H_RLMID1
* RLM_DISABLE_H_RLMID2
* RLM_DISABLE_H_DISKSN
* RLM_DISABLE_H_IPV6
* RLM_DISABLE_H_UUID

------

*******************
RLM Hostid Security
*******************

RLM hostids have varying levels of security. We describe these levels as:

* **Minimal (min)** - The hostid works anywhere - nothing is required to run on any machine.
* **Low** - The hostid is locked, but the data it is locked to is easily changeable, and in fact, 
  the data is meant to be changed and changing it is fully documented. (in the case of Windows 
  32-bit hostids, which are the volume serial number, PC manufacturers often create batches of PCs 
  with the same volume serial number).
* **Standard (std)** - The hostid is locked to something which is not designed to be changed. 
  Changing this requires some kind of hacking software, which may or may not be easily obtainable.

The following table shows RLM hostids and their security levels:

.. list-table::
	:header-rows: 1

	* - Hostid Type 
	  - Security Level 
	  - Notes
	* - ANY 
	  - min
	  - 
	* - DEMO 
	  - min
	  -
	* - 32 (or long) 
	  - low or std 
	  - Depends on the platform, see table below.
	* - disksn 
	  - std
	  -
	* - gc 
	  - std
	  - Deprecated.
	* - ip (or internet) 
	  - low
	  -
	* - ether 
	  - std
	  -
	* - rlmid1 
	  - std
	  -
	* - user 
	  - min
	  -
	* - host 
	  - min
	  -

The following table lists the security level of the 32-bit hostid type, by platform:

.. list-table::
	:header-rows: 1

	* - Platform 
	  - 32-bit hostid security
	* - hp_h1 
	  - std
	* - hp64_h1 
	  - std
	* - ibm_a1 
	  - std
	* - ibm64_a1 
	  - std
	* - x86_l1, x86_l2 
	  - low
	* - ppc64_l1 
	  - low
	* - x64_l1 
	  - low
	* - x86_m1 
	  - low
	* - x64_m1 
	  - low
	* - ppc_m1 
	  - low
	* - x64_s1 
	  - std
	* - sun_s1 
	  - std
	* - x64_s1 
	  - std
	* - x86_w3/4 
	  - low
	* - x64_w3/4 
	  - low