The file lsregistrationdaemon.conf is used to define what gets registered into the lookup service. The file allows a degree of flexibility in what is manually defined versus what is automatically discovered. In most cases, the defaults of this file will be suitable and you should not need to make any changes. Some situations where you might want to edit this file though are (this is not an exhaustive list):
You have a private lookup service and would like to only register to that service. See ls_instance Directive
You have a host with multiple network interfaces and would like to choose the interface on which a particular service or set of services run
You are not running a Toolkit (and thus don’t have the web UI) and would like to set location information, community tags or other values
You wish to override the auto-discovered defaults for one reason or another (e.g. maybe they are not correct or you would like to provide more detail)
The basic structure of the file is as follows:
A collection of top-level directives to control things like lookup service communication and how the daemon process runs
A list of site directives that group together elements with a common set of parameters
A list of host directives within those sites that represent the host to be registered. If the host in question is the host on which the LS Registration Daemon is running, than many of the values can be auto-discovered.
A list of service directives within those hosts that represent the services to be registered.
The lsregistrationdaemon.conf has the feature that almost any directive can be defined at a higher level in the configuration hierarchy and be inherited by all the descendents. For example, one can define the latitude and longitude directives at the top-level of the file. All registered hosts and services will in turn inherit these properties. In contrast, you can define them directly in each host directive if you want each individual host to have different values. You can even define both and have the more specific values in the host directive override the ones defined at a higher level in the hierarchy.
With these items in mind the remainder of this section contains a full reference of the options available in the lsregistrationdaemon.conf file.
The number of seconds in between checking and renewing a record in the lookup service
check_interval SECONDS
top level
Exactly one
3600
3.3 and later
The URL of the lookup service with which to register. If you are using a private lookup service, you must set the URL here.
ls_instance URL
top level
Exactly one
Chooses closest server in terms of round-trip time from the bootstrap file
The percentage difference in round-trip-time as a decimal (e.g. .1 = 10% ) that a new lookup service server must be in order for the client to considering switching to that service. For example, if the threshold is set as .1 (10%) and a lookup services is 100ms away, a new lookup service must be at most 90ms away for the client to consider switching.
ls_instance_latency_threshold NUMBER
top level
Exactly one
.1
4.0 and later
If no ls_instance is set, the the default behavior is to use the lookup service that is a) reachable and b) has the shortest round-trip-time. It’s possible due to outages, network changes, new lookup services in the bootstrap, etc the chosen lookup service will change over time. The daemon checks to see which lookup service to use every check interval. Rather than immediately changing, this value sets how many times a new lookup service must be returned before your daemon will switch to using it. This prevents frequent flapping between lookup services.
server_flap_threshold NUMBER
top level
Exactly one
3
3.4 and later
Indicates whether we want to automatically determine the value of any property not manually set in this file. If set to 1, it will try to determine as many fields as possible. If set to 0, all fields must be manually set. Manually set properties take precedence over any auto-discovered values.
autodiscover 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.4 and later
If autodiscover is enabled, indicates whether private IP addresses (RFC 1918 and RFC 4193) can be used if discovered. Generally you will only want to set this if you are using a private lookup service.
allow_internal_addresses 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.3 and later
The URL of the pScheduler instance to query for auto-discovering tests.
allow_internal_addresses 0|1
Zero or one
Defaults to https://ADDRESS/pscheduler where ADDRESS is the interface address
4.1 and later
Disables autodiscovery of pScheduler test types for interface
disable_autodiscover_tests 0|1
Zero or More
0
If autodiscover is enabled, any IPv4 address found will lead to an attempt to discover a DNS name via a reverse DNS query. This disables that reverse lookup and any value that would have used the discovered hostname will use the raw IPv4 address instead.
disable_ipv4_reverse_lookup 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.3 and later
If autodiscover is enabled, any IPv6 address found will lead to an attempt to discover a DNS name via a reverse DNS query. This disables that reverse lookup and any value that would have used the discovered hostname will use the raw IPv6 address instead.
disable_ipv6_reverse_lookup 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.3 and later
Disables registration of the enclosing block and any sub-blocks.
disabled 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.3 and later
Skips any automatic checks to see if a service is running and registers the record to the lookup service regardless of whether the item being registered is actually running or not.
force_up_status 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.3 and later
Indicates that the service runs on the same machine as the LS registration Daemon. This must be set for most autodiscover functionality to work, especially as pertains to hosts.
is_local 0|1
top level, site, host, interface, service, service_template
Zero or one
0
3.3 and later
Indicates the primary interface to use. When set, autodiscover will only register information for this interface when determining a service address
primary_interface IFNAME
top level, site, host, service, service_template
Zero or one
First interface encountered with an address
3.4 and later
A person responsible for managing the entity to be registered. See Administrators for more information.
<administrator>...</administrator>
top level, site, host, service, service_template
Zero or More
N/A
3.3 and later
The city in which the entity to be registered resides
city CITY
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
The ISO 3166 two-letter country code for the country in which the entity to be registered resides
country COUNTRY
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
The administrative domain in which the entity to be registered resides. Usually expressed as a DNS name (e.g. perfsonar.net).
domain DOMAIN
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
The latitude of the entity to be registered. Specified as a positive (north of the equator) or negative (south of the equator) decimal.
latitude LATITUDE
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
The longitude of the entity to be registered. Specified as a positive (east of the prime meridian) or negative (west of the prime meridian) decimal.
longitude LONGITUDE
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
The country specific region. For example, in the U.S. this value corresponds to the state. It should be the two-letter abbreviation if applicable.
region REGION
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
A grouping of elements that have similar configured properties, be it location, autodiscover settings or otherwise. See Sites for more information.
<site>...</site>
top level
Zero or More
N/A
N/A
The country specific postal code of the location where the entity to be registered resides.
zip_code ZIPCODE
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
The full name of the administrator. Either this field or email is required.
name NAME
Zero or One
N/A
N/A
3.3 and later
The email address of the administrator. Either this field or name is required.
email EMAIL
Zero or One
N/A
N/A
3.3 and later
The organization to which the administrator belongs
organization ORGANIZATION
Zero or One
N/A
N/A
3.3 and later
The phone number of the administrator
phone PHONE
Zero or One
N/A
N/A
3.3 and later
The name of the site
site_name NAME
top level, site, host, service, service_template
Zero or One
N/A
N/A
3.3 and later
A community string or project string to be registered. Often used as a way to define custom tags for registered entities.
site_name NAME
top level, site, host, service, service_template
Zero or More
N/A
N/A
3.3 and later
Indicates who may access this host to run tests. Valid values are public (anyone can access), private (only the owner’s local network can access), research-education (only those coming from R&E networks may access) or limited (some combination of the others, you should provide more detail in access_policy_notes).
access_policy POLICY
Zero or One
N/A
N/A
3.5 and later
A human-readable description of the access_policy. For example “Authenticate using username and password”. There is no defined form for this field and is intended as a way to provide additional information to those looking at the record.
access_policy_notes NOTES
Zero or One
N/A
N/A
3.5 and later
Indicates whether you want to autodiscover the list of interfaces on the host. Enabled if autodiscover Directive is set. Disabling this with autodiscover Directive enabled will turn-off interface discover but still allow other fields to be discovered.
autodiscover_interfaces 0|1
Zero or One
The value of autodiscover Directive
N/A
3.4 and later
The type of perfSONAR install. Examples include test-point, perfsonar-core, perfsonar-complete, and perfsonar-toolkit
bundle_type TYPE
Zero or One
N/A
The contents of /var/lib/perfsonar/bundles/bundle_type
3.5 and later
A DNS name (preferably) or IP that identifies the host
host_name NAME
Zero or One
N/A
The DNS hostname that matches a reverse lookup of the auto-discovered address of the host.
3.4 and later
Represents a manually defined interface on the host. See Interfaces for more details.
<interface>...<interface>
Zero or More
N/A
The list of interfaces on the host as reported by ifconfig
3.4 and later
The kernel and version running on the host.
os_kernel KERNEL
Zero or One
N/A
The OS name and version output separated by a space from /etc/redhat-release, /etc/os_version or /etc/debian_version depending on the OS.
3.4 and later
The name of the operating system (e.g. CentOS, Debian, etc).
os_name NAME
Zero or One
N/A
The OS name from /etc/redhat-release, /etc/os_version or /etc/debian_version depending on the OS.
3.4 and later
The version of the operating system.
os_version VERSION
Zero or One
N/A
The OS version from /etc/redhat-release, /etc/os_version or /etc/debian_version depending on the OS.
3.4 and later
The type of host. Valid values are zero or more of the following nren, regional, site-border, site-internal, science-dmz, exchange-point, test-host, default-path, backup-path
role ROLE
Zero or More
N/A
N/A
3.5 and later
The known maximum achievable throughput on this host. This is a manually set value based on experience with the hardware. For example, some low cost hosts may have a 1Gbps network interface, but processor limitations prevent it from ever achieving more than 500Mbps. Should be value followed by units (e.g. 1024Mbps, 1Gbps)
tcp_max_achievable BANDWIDTH
Zero or One
N/A
N/A
3.5 and later
The maximum throughput of the interface in bps.
capacity CAPACITY
Zero or One
N/A
The speed as reported by /sys/class/net/IF_NAME/speed. If not available, the speed as reported by ethtool.
3.3 and later
Removes test type from interface even if it is in the autodiscovery list
disable_test TEST_TYPE
Zero or More
N/A
A pscheduler test type that is allowed on this interface. For example throughput, latencybg or trace. Will be merged with autodiscovered values unless disable_autodiscover_tests set.
test TEST_TYPE
Zero or More
N/A
The tests found by querying pScheduler
The IP address or DNS name on which the service listens
address ADDRESS
top level, site, host, service, service_template
Zero or More
N/A
The auto-discovered primary address
3.3 and later
The method with which one may authenticate to this service.
authentication_type TYPE
top level, site, host, service, service_template
Zero or More
N/A
N/A
3.3 and later
Indicates whether you want to autodiscover the address on which the service listens. Enabled if autodiscover Directive is set. Disabling this with autodiscover Directive enabled will turn-off address discovery but still allow other fields to be discovered.
autodiscover_addresses 0|1
top level, site, host, service, service_template
Zero or One
The value of autodiscover Directive
N/A
3.3 and later
Indicates the service template from which to inherit properties
inherits TEMPLATENAME
Zero or One
N/A
N/A
3.3 and later
The port on which the service listens
port NUMBER
top level, site, host, service, service_template
Zero or One
Depends on the service type
N/A
3.3 and later
The version of the service
service_version VERSION
top level, site, host, service, service_template
Zero or One
Service dependent
N/A
3.3 and later
The type of the service. See description below for valid types.
type TYPE
Zero or One
Service dependent
N/A
3.3 and later
Valid values for this field are currently:
dashboard
gridftp
ma
owamp
twamp
ping
pscheduler
traceroute
For autodiscovery of information that requires contacting an HTTPS service, this is the path to the CA file that can be used to verify the identity of the server
autodiscover_ca_file FILE
Zero or One
N/A
N/A
3.4 and later
For autodiscovery of information that requires contacting an HTTPS service, this is the path to a directory of CA files that can be used to verify the identity of the server when using HTTPS
autodiscover_ca_path DIR
Zero or One
N/A
N/A
3.4 and later
Indicates whether or not to try to index results. Currently only traceroute data is supported. This will look at traceroute results in autodiscover_index_time_range and report unique hops.
autodiscover_indices 0|1
Zero or One
The value of autodiscover_tests
N/A
3.4 and later
If autodiscover_indices is enabled, the time range to query the MA for results to index in seconds.
autodiscover_index_time_range 0|1
Zero or One
604800
N/A
3.4 and later
The URL to contact to autodiscover details about an HTTP service
autodiscover_url URL
Zero or One
The value of service_locator Directive
N/A
For autodiscovery of information that requires contacting an HTTPS service, indicates whether the hostname must match the certificate common name
autodiscover_verify_hostname 0|1
Zero or One
0
N/A
3.4 and later
The port where a web service listens for HTTP connections
http_port PORT
Zero or One
80 (unless https_port Directive set, then this is left unset if no manual value provided)
N/A
3.4 and later
The URL of a web interface associated with a service
webui_url URL
Zero or One
The manually set address and port with path /maddash-webui
The auto-detected address and port with path /maddash-webui
3.4 and later
Represents a measurement stored in an archive. See Measurement Archive Tests for more details.
<test>...</test>
Zero or More
N/A
The tests found by querying the MA metadata
The destination of the test as an IP address
destination IP
Exactly One
N/A
The destination of a given test as reported by the queried MA
The URL of the MA storing this test
ma_locator URL
One or More
N/A
The URL of the queried MA
The IP address of the test initiator
measurement_agent IP
Exactly one
N/A
The measurement-agent of a given test as reported by the queried MA
The URI used to access a particular test
metadata_uri URI
Exactly one
N/A
The uri of a given test as reported by the queried MA
In general, you will not manually set this value. A summarized value derived from the results of the test that can be searched by LS clients.
result_index VALUE
Zero or More
N/A
Type dependent. For traceroute tests, a unique hop found in the results.
The source of the test as an IP address
source IP
Exactly One
N/A
The source of a given test as reported by the queried MA
The name of the tool used to perform a measurement
tool_name TOOL
Exactly One
N/A
The tool-name of a given test as reported by the queried MA
The frequency in seconds to check the lsregistrationdaemon.conf file for changes.
check_config_interval SECONDS
top level
Zero or One
60
4.0 and later
The location of the file containing a UUID to be registered with each record in the client-uuid field. If the file does not exist it will be created and populated with a random UUID.
client_uuid_file FILE
top level
Zero or One
/var/lib/perfsonar/lsregistrationdaemon/client_uuid
The group to run the daemon as. Overridden by the –group command-line switch.
group GID
top level
Zero or One
N/A
The location of the SQLite database where registration keys are kept. Registration keys are assigned by the lookup service when a record is first created and are used for subsequent renewals.
ls_key_db DB
top level
Zero or One
/var/lib/perfsonar/lsregistrationdaemon/lsKey.db
The PID file location. Overridden by the –pidfile command-line switch.
pidfile FILE
top level
Zero or One
/var/run/ls_registration_daemon.pid
The user to run the daemon as. Overridden by the –user command-line switch.
user UID
top level
Zero or One
N/A