blob: 010498d2e6b869e53b72e68f306490f6f1f5eca5 [file] [log] [blame]
Yingdi Yu4e99f532014-08-25 19:40:57 -07001client.conf
2===========
3
Davide Pesavento01cea502021-07-31 19:25:42 -04004Description
5-----------
6
Yingdi Yu4e99f532014-08-25 19:40:57 -07007System configuration of NDN platform is specified in ``client.conf``.
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -07008
9The configuration file ``client.conf`` is looked up in several directories in the following order:
10
Davide Pesavento534b8412018-12-08 19:19:09 -050011- ``$HOME/.ndn``: user-specific settings
Davide Pesavento933a5672020-07-03 22:32:43 -040012- ``SYSCONFDIR/ndn``: system-wide settings (where ``SYSCONFDIR`` can be ``/usr/local/etc``,
13 ``/opt/local/etc``, or other, depending on how the library is configured)
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070014- ``/etc/ndn``: default system-wide settings
15
Davide Pesavento933a5672020-07-03 22:32:43 -040016Here is an example of ``client.conf`` for the current ndn-cxx package:
Yingdi Yu4e99f532014-08-25 19:40:57 -070017
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070018.. literalinclude:: ../../client.conf.sample
Davide Pesavento01cea502021-07-31 19:25:42 -040019 :language: ini
Yingdi Yu4e99f532014-08-25 19:40:57 -070020
Yingdi Yu4e99f532014-08-25 19:40:57 -070021
Davide Pesavento01cea502021-07-31 19:25:42 -040022Forwarder
23---------
Yingdi Yu4e99f532014-08-25 19:40:57 -070024
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070025transport
Eric Newberry52a803c2020-04-07 00:01:12 -070026 FaceUri for default connection toward local NDN forwarder. Only ``unix``, ``tcp``, ``tcp4``, and
27 ``tcp6`` FaceUris can be specified here.
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070028
Eric Newberry52a803c2020-04-07 00:01:12 -070029 By default, ``unix:///run/nfd.sock`` is used on Linux and ``unix:///var/run/nfd.sock`` is used on
30 other platforms.
Yingdi Yu4e99f532014-08-25 19:40:57 -070031
Davide Pesavento534b8412018-12-08 19:19:09 -050032 .. note::
Niv Sardi8ac87542016-12-13 15:38:06 -030033 This value can be overridden using the ``NDN_CLIENT_TRANSPORT`` environment variable.
Yingdi Yu4e99f532014-08-25 19:40:57 -070034
Davide Pesavento534b8412018-12-08 19:19:09 -050035
Yingdi Yu4e99f532014-08-25 19:40:57 -070036Key Management
37--------------
38
Yingdi Yu4e99f532014-08-25 19:40:57 -070039pib
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070040 The public key information for each private key stored in TPM. The format for this setting is::
Yingdi Yu4e99f532014-08-25 19:40:57 -070041
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070042 pib=[scheme]:[location]
Yingdi Yu4e99f532014-08-25 19:40:57 -070043
Davide Pesavento01cea502021-07-31 19:25:42 -040044 Possible values for ``[scheme]`` are:
Yingdi Yu4e99f532014-08-25 19:40:57 -070045
Davide Pesavento01cea502021-07-31 19:25:42 -040046 * ``pib-sqlite3``: local PIB implementation using the SQLite3 storage engine.
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070047
48 Possible values for ``[location]``:
49
Davide Pesavento01cea502021-07-31 19:25:42 -040050 * absolute path where the SQLite3 database will be stored
51 * relative path (relative to ``client.conf``)
52 * empty: the default path ``$HOME/.ndn`` will be used
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070053
Davide Pesavento01cea502021-07-31 19:25:42 -040054 When ``[location]`` is empty, the trailing ``:`` can be omitted. For example::
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070055
56 pib=pib-sqlite3
57
Niv Sardi8ac87542016-12-13 15:38:06 -030058 Changing PIB scheme without changing location is **not** allowed. If a change like this is
59 necessary, the whole backend storage must be destroyed. For example, when the default location is
60 used::
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070061
62 rm -rf ~/.ndn/ndnsec-*
63
Davide Pesavento534b8412018-12-08 19:19:09 -050064 It is not recommended to share the same directory between machines, e.g. via NFS.
Junxiao Shi67fba7f2016-09-09 13:40:05 +000065 Simultaneous access from multiple machines may cause errors.
66
Davide Pesavento534b8412018-12-08 19:19:09 -050067 .. note::
Niv Sardi8ac87542016-12-13 15:38:06 -030068 This value can be overridden using the ``NDN_CLIENT_PIB`` environment variable.
Alexander Afanasyev57e00362016-06-23 13:22:54 -070069
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070070tpm
71 Trusted Platform Module (TPM) where the private keys are stored. The format for this setting
72 is::
73
74 tpm=[scheme]:[location]
75
Davide Pesavento01cea502021-07-31 19:25:42 -040076 Possible values for ``[scheme]`` are:
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070077
Davide Pesaventodc3575f2022-07-30 21:10:34 -040078 * ``tpm-osxkeychain`` (default on macOS): secure storage of private keys in the macOS
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070079 Keychain with OS-provided access restrictions.
80
Davide Pesavento01cea502021-07-31 19:25:42 -040081 The ``[location]`` parameter is ignored.
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070082
Davide Pesavento534b8412018-12-08 19:19:09 -050083 May not work for daemon applications, as user interaction may be required to access the
84 macOS Keychain.
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070085
Davide Pesavento534b8412018-12-08 19:19:09 -050086 * ``tpm-file`` (default on all other platforms): file-based storage of private keys.
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070087
88 Possible values for ``[location]``:
89
90 * absolute path to directory that will store private/public key files (unencrypted with
91 ``0700`` permission)
Davide Pesavento01cea502021-07-31 19:25:42 -040092 * relative path (relative to ``client.conf``)
93 * empty: the default path ``$HOME/.ndn/ndnsec-tpm-file`` will be used
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070094
Davide Pesavento01cea502021-07-31 19:25:42 -040095 When ``[location]`` is empty, the trailing ``:`` can be omitted. For example::
Alexander Afanasyev5208d0e2015-06-03 16:42:09 -070096
97 tpm=tpm-file
98
Davide Pesavento534b8412018-12-08 19:19:09 -050099 **Changing the ``tpm`` setting is only possible together with ``pib`` setting. Otherwise,
100 an error will be generated during PIB/TPM access.**
Alexander Afanasyev57e00362016-06-23 13:22:54 -0700101
Davide Pesavento534b8412018-12-08 19:19:09 -0500102 It is not recommended to share the same directory between machines, e.g. via NFS.
Junxiao Shi67fba7f2016-09-09 13:40:05 +0000103 Simultaneous access from multiple machines may cause errors.
104
Davide Pesavento534b8412018-12-08 19:19:09 -0500105 .. note::
Niv Sardi8ac87542016-12-13 15:38:06 -0300106 This value can be overridden using the ``NDN_CLIENT_TPM`` environment variable.