.. Hey, Emacs this is -*- rst -*- This file follows reStructuredText markup syntax; see http://docutils.sf.net/rst.html for more information. .. configuration: .. _CORS: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing .. _Flask: http://flask.pocoo.org/ .. _JWT: https://python-jose.readthedocs.io/en/latest/index.html .. _engines: https://docs.sqlalchemy.org/en/latest/core/engines.html ================= Configuration ================= All the information regarding the system is stored in a configuration file. The default configuration file is stored in your home directory: ``~/.acpy/api.config`` but you can specify a different location from the command line with the `-c` option. If no configuration file is found, it will copy an example configuration file in ``~/.acpy/api.config``. The example contains placeholders for all required values. General settings ================= The following parameters are available as general settings: 1. CORS_ can be enabled, by default it is disabled 2. ``secret`` for Flask_, autogenerated when the config file is created 3. ``port`` for the api, default is 8080 4. ``run_time`` stores the runtime information in a file, default is ``~/.acpy/run_time.data`` Logging settings ================= The following parameters are available for logging: 1. ``log_file`` specifies the location of the logfile, default is ``~/.acpy/acpy.log``. If left empty, no log file is generated. 2. ``max_bytes`` is the maximum size of a logfile before it is rotated, default is 2.5MB. 3. ``backup_count`` is the maximum amount of logfiles to keep of max_bytes, default is 5. The admin account ================== The default admin account behaves as a service account: 1. ``access`` is the access code for the admin account (analog to username) 2. ``secret`` is the secret code for the admin account (analog to password) the password needs to be passed as sha256. JWT token settings =================== Users and services request a token by calling the ``login`` service. This service returns a JWT_ token. 1. ``issuer`` is the name of the token issuer, this should reflect the URI of the API. 2. ``secret`` is the secret that is used for encoding the token, if left empty the FLASK_ shared secret is used. 3. ``lifetime`` is the token lifetime in seconds, default is 3600. 4. ``algorithm`` is the encryption algorithm for the token, default is HS256. Database settings ================== All data is stored in a database, the connection needs to be specified in the configuration. By default we store to memory. 1. ``connection`` specifies the database connection, default is sqlite:// * example of a mariadb connection: ``mysql://scott:tiger@localhost/test`` * example of a postgres connection: ``postgresql://scott:tiger@localhost/mydatabase`` We use SQLAlchemy, so for all options see engines_ LDAP settings ============== For authenticating users configure an LDAP compliant connection. 1. ``host`` ldap server without protocol. 2. ``port`` ldap port 3. ``ssl`` secure connection 4. ``base_dn`` root for the users 5. ``rdn_attr`` relative distinguished name (usually ``uid`` or ``cn``) 6. ``login_attr`` what field to use for username. 7. ``bind_user`` user account that has read access on the ``base_dn`` 8. ``bind_pass`` password for ``bind_user``