> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Initial configuration > Configure your gateway server to handle client requests, manage resources, and communicate with Gateway Manager and runner nodes. Initial configuration of your gateway cluster involves setting up the gateway server to handle client requests, manage resources, and communicate with Gateway Manager and runner nodes. Different sections of the configuration file apply to specific nodes and communication scenarios. ## Configuration file structure The configuration file is located at `/etc/gateway/gateway.conf` for RPM/DEB installations or managed through environment variables for containerized deployments. Each configuration section serves specific node types and communication requirements: * `[application]`: Global settings applied to all node types * `[server]`: Settings specific to gateway server nodes * `[client]`: Settings specific to gateway client nodes * `[connect]`: Settings for Gateway Manager connectivity (applies to server nodes) * `[runner]`: Settings specific to gateway runner nodes * `[store]`: Database backend configuration (applies to server and runner nodes in distributed execution deployment models) * `[log]`, `[features]`, `[secrets]`: Shared settings across node types ## Essential configuration settings After installing Gateway Manager and Gateway, configure each node by updating the appropriate configuration variables. The following tabs provide examples of the most common settings you need to configure before starting your gateway cluster. To view an example configuration file, see [Configuration variables](./configuration-variables-overview). #### Application mode **Applies to**: All nodes Set the application mode to server to manage gateway resources: ```bash [application] mode = server cluster_id = 'cluster_1' working_dir = /var/lib/gateway # CA certificate for mutual TLS verification ca_certificate_file = /etc/gateway/certificates/ca.pem ``` For more information, see [Application modes](./application-modes). #### Server **Applies to**: Server nodes only Configure server listening parameters: ```bash [server] listen_address = 0.0.0.0 port = 50051 use_tls = true # Server certificates for mutual TLS between nodes (client-server and server-runner) certificate_file = /etc/gateway/certificates/server.pem private_key_file = /etc/gateway/certificates/server-key.pem api_key_expiration = 1440 runtime_data_dir = /var/lib/gateway distributed_execution = false ``` For more information, see [Server variables](./gateway-server-variables). #### Gateway Manager connection **Applies to**: Server nodes only **Prerequisites** Before you copy the following example `[connect]` configuration to your server host machine, complete the following prerequisites. **Create and upload certificates** Create certificates for secure communication between your gateway cluster and Gateway Manager. Gateway Manager supports self-signed certificates, CA-issued certificates, and CA-issued wildcard certificates. For detailed procedures, see [Create certificates](./create-certificates). **Identify your Itential Platform server** The `GATEWAY_CONNECT_HOSTS` value identifies your Itential Platform server. How you identify your the server varies based on your Itential Platform deployment type: #### Cloud 1. Identify your Itential Platform server's URL, for example: `acme-dev-iap01.iap-prod.itential.io` 2. Add `-gwm` to the server name before the first period (.): `acme-dev-iap01-gwm.iap-prod.itential.io` 3. Add `:443` to the end: `acme-dev-iap01-gwm.iap-prod.itential.io:443` **Final result:** `GATEWAY_CONNECT_HOSTS: "acme-dev-iap01-gwm.iap-prod.itential.io:443"` #### On-prem deployment Update the `GATEWAY_CONNECT_HOSTS` value to match the hostname or IP address of the server where you installed your Gateway Manager instance, including the port (e.g., `10.0.0.1:8080`). By default, Gateway Manager uses port 8080 for gateway connections. **Example:** `GATEWAY_CONNECT_HOSTS: "10.0.0.1:8080"` **Configure connection to Gateway Manager:** ```bash [connect] enabled = true # Update this to match your Gateway Manager server hostname/IP and port (8080 by default) hosts = 'gateway-manager-host:8080' certificate_file = '/etc/gateway/certificates/gw-manager.pem' private_key_file = '/etc/gateway/certificates/gw-manager-key.pem' insecure_tls = false ``` After you complete your initial configuration, register your gateway cluster in Gateway Manager. For more information, see [Connection variables](./gateway-connect-variables). #### Logging **Applies to**: All nodes Configure logging levels and output: ```bash [log] level = INFO file_enabled = true server_dir = /var/log/gateway console_json = false file_json = false timestamp_timezone = utc ``` For more information, see [Log variables](./gateway-log-variables). #### Features **Applies to**: All nodes Enable or disable specific features: ```bash [features] ansible_enabled = true python_enabled = true opentofu_enabled = true hostkeys_enabled = true ``` For more information, see [Feature variables](./gateway-feature-variables). --- ## Server startup and management Once your configuration is complete, start your gateway server to begin accepting client connections. The startup process differs between RPM/DEB installations and container deployments. ### RPM/DEB installations ```bash # Start the server sudo systemctl start iagctl # Enable auto-start sudo systemctl enable iagctl # Check status sudo systemctl status iagctl # View logs sudo journalctl -u iagctl -f ``` ### Container deployments ```bash # Start server container docker compose up -d # View logs docker compose logs -f gateway5-server # Stop server docker compose down ``` --- ## Initial admin setup On first startup, Gateway creates a temporary admin account for initial configuration. Gateway clients use this account to connect to the server and configure services and resources. Find the credentials in the logs: ``` === CREATED TEMPORARY ADMIN username: admin password: admin === ``` --- ## Learn more * For detailed descriptions on all configuration variables, see [Configuration variables](./configuration-variables-overview). * For procedures on configuring gateway clients, see [Configure gateway client](./client-configuration). * For more information on configuring runner nodes, see [Configure distributed execution clusters](./distributed-execution-clusters). * For more information on configuring multiple server nodes, see [Configure high availability clusters](./high-availability-clusters). * For more information on configuring your database backend, see: * [etcd database configuration](./configure-etcd-database) * [Amazon DynamoDB table configuration](./configure-dynamodb-table)