Faraday Server Configuration Guide¶

Introduction¶

This documentation explains how to configure the Faraday Server using the server.ini file. Faraday uses a robust configuration system that ensures the server operates correctly while allowing users to customize behavior to fit their specific environment.

The server.ini file is the primary place where you can adjust server settings, database connections, and storage paths. You should interact with this file during the initial setup or when you need to change how Faraday communicates with its components (like the database or Redis).

Sections¶

The server.ini file is organized into several sections, each controlling a different aspect of the Faraday Server. Sections are identified by a name enclosed in square brackets (for example, [faraday_server]). All settings following a section header belong to that specific group until a new section header appears.

faraday_server¶

This section controls the core behavior of the Faraday Server.

Setting	Description	Recommended/Example Values	Effect of Change
`port`	The network port the server listens on.	`5985` (Default)	Changes the port used to access Faraday (e.g., `http://localhost:5985`).
`bind_address`	The IP address the server "binds" to.	`0.0.0.0` (Listen on all interfaces), `127.0.0.1` (Local only)	Controls if the server is accessible from other computers or only locally.
`api_token_expiration`	How long an API token remains valid (in seconds).	`604800` (7 days)	Longer values reduce the frequency of re-authentication; shorter values are more secure.
`session_timeout`	How long a user session lasts (in hours).	`24`	Determines how long you can stay logged into the web interface before being logged out.
`delete_report_after_process`	Whether to delete uploaded reports after they are processed.	`true` or `false`	If `true`, keeps your storage clean. If `false`, keeps a backup of all uploaded reports.
`redis_session_storage`	The address/hostname for the Redis server used for sessions.	`faraday-redis`, `127.0.0.1`	Changes where Faraday stores active session data.
`notifications_enabled`	Enables or disables the notification system.	`true` or `false`	Turns on/off alerts and notifications within Faraday.
`websocket_server_fqdn`	The address used for real-time updates (WebSockets).	`https://faraday.local`	Ensures real-time dashboard updates work correctly across the network.
`websocket_server_port` (deprecated)	The port used for real-time updates.	`5000`	Changes the port dedicated to real-time communication.
`secure_cookies`	Ensures cookies are only sent over HTTPS.	`true` (Recommended for production)	Enhances security by requiring encrypted connections for session data.
`agent_token_expiration`	How long an agent token remains valid (in seconds).	`60`	Controls the lifespan of tokens used by Faraday agents.
`forwarded_for_index`	The index of the IP address in the `X-Forwarded-For` header.	`1`	Used when the server is behind multiple proxies to identify the correct client IP.
`celery_enabled`	Enables or disables the background task worker (Celery).	`true` or `false`	Turns off background tasks like report processing if disabled.
`celery_broker_url`	The connection URL for the Celery message broker (Redis/RabbitMQ).	`redis://127.0.0.1:6379/0`, `ampq://user:pass@127.0.0.1:5671/example_queue`	Changes where background tasks are queued.
`celery_backend_url`	The connection URL for the Celery results backend (Redis).	`redis://127.0.0.1:6379/0`	Changes where results of background tasks are stored.
`idle_session_timeout`	Automatically logs out inactive users after this many seconds.	`0` (Disabled by default)	Enhances security by terminating sessions that have been idle.
`debug`	Enables or disables debug mode.	`false` (Recommended for production)	Provides more detailed error messages and logs for troubleshooting.
`secret_key`	A secret key used for signing session cookies.	(Generated automatically)	Crucial for security; changing it will log out all users.
`agent_registration_secret`	Secret key used for registering new agents.	(Generated automatically)	Ensures only authorized agents can connect to your server.
`bulk_create_workers` (depracated)	Number of worker processes for bulk creation tasks.	`4`	Can improve performance of large imports on multi-core systems.
`max_task_message_size`	Maximum size of a task message (in bytes).	`5242880` (5MB)	Prevents extremely large reports from overwhelming the task queue.
`celery_max_tasks_per_child`	How many tasks a worker process handles before restarting.	`50`	Helps prevent memory leaks in long-running background workers.
`elk_enabled`	Enables or disables ELK stack integration.	`true` or `false`	Sends logs and data to an Elasticsearch server if enabled.
`elk_url`	The address of your Elasticsearch server.	`http://localhost`	Where to send data for ELK integration.
`elk_port`	The port your Elasticsearch server is listening on.	`9200`	The port used for ELK communication.

limiter¶

This section controls rate limiting for security.

Setting	Description	Example Value	Effect of Change
`enabled`	Enables or disables the login rate limiter.	`true` or `false`	Protects against brute-force attacks on the login page.
`login_limit`	The maximum number of login attempts allowed per time period.	`10/minutes`	Restricts how quickly users can try to log in.

logger¶

This section configures server logging.

Setting	Description	Example Value	Effect of Change
`use_rfc5424_formatter`	Uses a standardized log format (RFC 5424).	`true` or `false`	Makes logs easier to process for some external log management tools.

gitlab_integration¶

Settings for connecting with GitLab.

Setting	Description	Example Value	Effect of Change
`ssl_cert_path`	Path to an SSL certificate for GitLab connections.	`/path/to/cert.pem`	Allows Faraday to communicate securely with a self-signed GitLab instance.

storage¶

This section defines where Faraday stores its files.

Setting	Description	Example Value	Effect of Change
`path`	The folder on your hard drive where Faraday saves data.	`/home/faraday/.faraday/storage`	Changes the physical location of stored data (useful if you have a separate storage drive).

database¶

This section handles the connection to your database.

Setting	Description	Example Value	Effect of Change
`connection_string`	The "address" and credentials for your database.	`postgresql+psycopg2://USER:PASS@HOST/DB`	Tells Faraday how to find and log into its primary database.