XiVO dird configuration
There are three sources of configuration for xivo-dird:
the main configuration file
the sources configuration directory
The command-line options have priority over the main configuration file options.
Main Configuration File
Default location: /etc/xivo-dird/config.yml
. Format: YAML
The default location may be overwritten by the command line options.
Here’s an example of the main configuration file:
1debug: False
2foreground: False
3log_filename: /var/log/xivo-dird.log
4log_level: info
5pid_filename: /var/run/xivo-dird/xivo-dird.pid
6source_config_dir: /etc/xivo-dird/sources.d
7user: www-data
8
9rest_api:
10 wsgi_socket: /var/run/xivo-dird/xivo-dird.sock
11
12enabled_plugins:
13 backends:
14 - csv
15 - ldap
16 - phonebook
17 services:
18 - lookup
19 views:
20 - cisco_view
21 - default_json
22
23views:
24 displays:
25 switchboard_display:
26 -
27 title: Firstname
28 default: Unknown
29 field: firstname
30 type: name
31 -
32 title: Lastname
33 default: Unknown
34 field: lastname
35 type: name
36 default_display:
37 -
38 title: Firstname
39 field: fn
40 type: name
41 -
42 title: Location
43 default: Canada
44 field: country
45 -
46 title: Number
47 field: number
48 type: number
49 displays_phone:
50 default:
51 name:
52 - display_name
53 number:
54 -
55 field:
56 - phone
57 -
58 field:
59 - phone_mobile
60 name_format: "{name} (Mobile)"
61 profile_to_display:
62 default: default_display
63 switchboard: switchboard_display
64 profile_to_display_phone:
65 default: default
66
67services:
68 lookup:
69 default:
70 sources:
71 - my_csv
72 - ldap_quebec
73 timeout: 0.5
74 switchboard:
75 sources:
76 - my_csv
77 - xivo_phonebook
78 - ldap_quebec
79 timeout: 1
80
81sources:
82 my_source:
83 name: my_source
84 type: ldap
85 ldap_option1: value
86 ldap_option2: value
87 ...
Root section
- debug
Enable log debug messages. Overrides
log_level
. Default:False
.- foreground
Foreground, don’t daemonize. Default:
False
.- log_filename
File to write logs to. Default:
/var/log/xivo-dird.log
.- log_level
Logs messages with LOG_LEVEL details. Must be one of:
critical
,error
,warning
,info
,debug
. Default:info
.- pid_filename
File used as lock to avoid multiple xivo-dird instances. Default:
/var/run/xivo-dird/xivo-dird.pid
.- source_config_dir
The directory from which sources configuration are read. See Sources Configuration. Default:
/etc/xivo-dird/sources.d
.- user
The owner of the process. Default:
www-data
.
enabled_plugins section
This sections controls which plugins are to be loaded at xivo-dird startup. All plugin types must have at least one plugin enabled, or xivo-dird will not start. For back-end plugins, sources using a back-end plugin that is not enabled will be ignored.
views section
- displays
A dictionary describing the content of each display. The key is the display’s name, and the value are the display’s content.
The display content is a list of fields. Each field is a dictionary with the following keys:
title: The label of the field
default: The default value of the field
type: An arbitrary identifier of the field. May be used by consumers to identify the field without matching the label. For meaningful values inside XiVO, see Integration of XiVO dird with the rest of XiVO.
field: the key of the data from the source that will be used for this field.
The display may be used by a plugin view to configure which fields are to be presented to the consumer.
- displays_phone
A dictionary describing the content of phone-related displays. Like
displays
, the key is the display’s name and the value is the display’s content. These displays are used by phone-related view plugins, like thecisco_view
plugin.The display content contains 2 keys,
name
andnumber
.The value of the
name
key is a list of source result fields. For a given source result, the first field that will return a non-empty value will be used as the display name on the phone. For example, ifname
is configured with["display_name", "name"]
and you have a source result with fields{"display_name": "", "name": "Bob"}
, then “Bob” will be displayed on the phone.The value of the
number
key is a list of number item. Each item is composed of a dictionary containing at least afield
key, and optionally aname_format
key. For example, if you have the following number configuration:name: - display_name number: - field: - phone - field: - phone_mobile name_format: "{name} (Mobile)"
and you have a source result
{"display_name": "Bob", "phone": "101", "phone_mobile": "102"}
, then 2 results will be displayed on your phone:“Bob”, with number “101”
“Bob (Mobile)”, with number “102”
The
name_format
value is a python format string. There’s two substitution variables available,{name}
and{number}
.- profile_to_display
A dictionary associating a profile to a display. It allows xivo-dird to use the right display when a consumer makes a query with a profile. The key is the profile name and the value is the display name.
- profile_to_display_phone:
A dictionary associating a profile to a phone display. This is similar to
profile_to_display
, but only used by phone-related view plugins.
services section
This section is a dictionary whose keys are the service plugin name and values are the configuration of that service. Hence the content of the value is dependent of the service plugin. See the documentation of the service plugin (Stock Plugins Documentation).
sources section
This section is a dictionary whose keys are the source name and values are the configuration for that source. See the Sources Configuration section for more details about source configuration.
Sources Configuration
There are two ways to configure sources:
in the sources section of the main configuration
in files of a directory, one file for each source:
Default directory location
/etc/xivo-dird/sources.d
Files format: YAML
File names are ignored
Each file listed in this directory will be read and used to create a data source for xivo-dird.
Here is an example of a CSV source configuration in its own file:
1type: csv
2name: my_contacts_in_a_csv_file
3file: /usr/local/share/my_contacts.csv
4unique_column: id
5searched_columns:
6 - fn
7 - ln
8format_columns:
9 name: "{fn} {ln}"
10 number: "{num}"
This is strictly equivalent in the main configuration file:
1sources:
2 my_contacts_in_a_csv_file:
3 type: csv
4 name: my_contacts_in_a_csv_file
5 file: /usr/local/share/my_contacts.csv
6 unique_column: id
7 searched_columns:
8 - fn
9 - ln
10 source_to_display_columns:
11 ln: lastname
12 fn: firstname
13 num: number
- type
the type of the source. It must be the same than the name of one of the enabled back-end plugins.
- name
is the name of this given configuration. The name is used to associate the source to profiles. The value is arbitrary, but it must be unique across all sources.
Warning
Changing the name of the source will make all favorites in that source disappear. There is currently no tool to help you migrate favorites between source names, so choose your source names carefully.
The other options are dependent on the source type (the back-end used). See the documentation of the back-end plugin (Stock Plugins Documentation). However, the following keys should be present in all source configurations:
- first_matched_columns (optional)
the columns used for the reverse lookup. Any column having the search term will be a reverse lookup result.
- format_columns (optional)
a mapping between result fields and a format string. The new key will be added to the result, if this name already exists in the result, it will be replaced with the new value. The syntax is a python format string. See https://docs.python.org/2/library/string.html#formatspec for a complete reference.
- searched_columns (optional)
the columns used for the lookup. Any column containing the search term substring will be a lookup result.
- unique_column (optional)
This column is what makes an entry unique in this source. The
unique_column
is used to build theuid
that is passed to the list method to fetch a list of results by unique ids. This is necessary for listing and identifying favorites.