Admin Module

givc.admin.enable

Whether to enable the GIVC admin module, which is responsible for managing the system. The admin module is responsible for registration, monitoring, and proxying commands across a virtualized system of host, system VMs, and application VMs.

Type: boolean

Default:

false

givc.admin.accessControl

Access control settings for the GIVC admin module.

Type: submodule

Default:

{ }

givc.admin.accessControl.enable

Whether to enable Enable GIVC Access Control system. GIVC access control system is based on Cedar policies. Policies are generated for givc agents based on the configuration defined in agentRules and for admin based on adminRules. .

Type: boolean

Default:

false

Example:

true

givc.admin.accessControl.adminRules

Defines the access control policies for the GIVC Admin server. The Admin server acts as a centralized controller. Direct agent-to-agent communication is generally discouraged, so the Admin server primarily functions as a proxy routing requests between agents. Additionally, the Admin server can consume and process requests directed at itself. This option controls the specific set of gRPC requests permitted from a source VM to either a target VM (proxy mode) or to the Admin server itself (consumer mode).

Example Proxy Rule: from = [ "gui-vm" ]; to = [ "app-vm" ]; permittedRequests = [ "StartApplication" ]; (Allows gui-vm to ask the Admin to start an application on app-vm)

Example Consumer Rule: from = [ "gui-vm" ]; to = [ ]; permittedRequests = [ "RegisterService" ]; (Allows gui-vm to call RegisterService directly on the Admin server)

Type: list of (submodule)

Default:

[ ]

Example:

[
  {
    from = [
      "gui-vm"
      "app-vm"
    ];
    permittedRequests = [
      "systemd"
    ];
    to = [
      "business-vm"
    ];
  }
]

givc.admin.accessControl.adminRules.*.from

A list of source VM identities (callers) permitted to initiate a request listed in the ‘permittedRequests’ option. This defines who is originating the request to admin.

Type: list of string

Default:

[ ]

givc.admin.accessControl.adminRules.*.permittedRequests

A list of specific gRPC methods that the callers listed in from are allowed to execute.

Example Proxy Rule: from = [ "gui-vm" ]; to = [ "app-vm" ]; permittedRequests = [ "StartApplication" ]; (Allows gui-vm to ask the Admin to start an application on app-vm)

Example Consumer Rule: from = [ "gui-vm" ]; to = [ ]; permittedRequests = [ "RegisterService" ]; (Allows gui-vm to call RegisterService directly on the Admin server)

Type: list of string

Default:

[ ]

givc.admin.accessControl.adminRules.*.to

A list of allowed destination VMs for the requests specified in permittedRequests. The Admin server is the default consumer unless a destination VM is specified in the request at runtime.

Proxy access: To allow forwarding to a target VM, list the target VM here (e.g., [ "app-vm" ]).
Consumer access only: Leave this empty ([ ]) to restrict the rule so that the Admin only processes the request itself.

Type: list of string

Default:

[ ]

givc.admin.addresses

List of addresses for the admin service to listen on. Requires a list of type transportSubmodule.

Type: list of (submodule)

Default:

addresses = [
  {
    name = "localhost";
    addr = "127.0.0.1";
    protocol = "tcp";
    port = "9000";
  }
];

Example:

addresses = [
  {
    name = "admin-vm";
    addr = "192.168.100.3";
    protocol = "tcp";
    port = "9001";
  }
  {
    name = "admin-vm";
    addr = "unix:///run/givc-admin.sock";
    protocol = "unix";
    # port is ignored
  }
];

givc.admin.addresses.*.addr

Address identifier. Can be one of IPv4 address, vsock address, or unix socket path.

Type: string

Default:

"127.0.0.1"

givc.admin.addresses.*.name

Identifier for network, host, and/or TLS name.

Type: string

Default:

"localhost"

givc.admin.addresses.*.port

Port identifier for TCP or vsock addresses. Ignored for unix socket addresses.

Type: string

Default:

"9000"

givc.admin.addresses.*.protocol

Protocol identifier. Can be one of ‘tcp’, ‘unix’, or ‘vsock’.

Type: one of “tcp”, “unix”, “vsock”

Default:

"tcp"

givc.admin.debug

Whether to enable givc-admin debug logging. This increases the verbosity of the logs.

Type: boolean

Default:

false

Example:

true

givc.admin.name

Network name of the host running the admin service.

Caution This is used to validate the TLS host name and must match the names used in the transport configurations (addresses).

Type: string

Default:

"localhost"

givc.admin.policyAdmin.enable

Whether to enable policy admin.

Type: boolean

Default:

false

Example:

true

givc.admin.policyAdmin.factoryPolicies.enable

Whether to enable Boot strap policies from default git URL.

Type: boolean

Default:

false

Example:

true

givc.admin.policyAdmin.factoryPolicies.rev

Rev of the default policies in the policy repository

Type: null or string

Default:

null

givc.admin.policyAdmin.factoryPolicies.sha256

SHA of the rev of the default policies in the policy repository

Type: null or string

Default:

null

givc.admin.policyAdmin.factoryPolicies.url

Git URL of policy repository

Type: null or string

Default:

""

givc.admin.policyAdmin.policies

Map of distributed policies

Type: attribute set of (submodule)

Default:

{ }

givc.admin.policyAdmin.policies.<name>.perPolicyUpdater.poll_interval_secs

Polling interval for the specific policy artifact

Type: signed integer

Default:

givc.admin.policyAdmin.policies.<name>.perPolicyUpdater.url

URL for the specific policy artifact, ignored if perPolicy updater is disabled

Type: null or string

Default:

""

givc.admin.policyAdmin.policies.<name>.vms

List of VMs this policy applies to

Type: list of string

Default:

[ ]

givc.admin.policyAdmin.storePath

Directory path for policy storage.

Type: string

Default:

"/etc/policies"

givc.admin.policyAdmin.updater.gitURL.enable

Whether to enable updates from default git URL.

Type: boolean

Default:

false

Example:

true

givc.admin.policyAdmin.updater.gitURL.poll_interval_secs

Global polling interval for the centralized repo

Type: signed integer

Default:

givc.admin.policyAdmin.updater.gitURL.ref

Git reference (branch/tag)

Type: string

Default:

"master"

givc.admin.policyAdmin.updater.gitURL.url

Git URL of policy repository

Type: null or string

Default:

""

givc.admin.policyAdmin.updater.perPolicy.enable

Whether to enable updates per policy.

Type: boolean

Default:

false

Example:

true

givc.admin.services

List of microvm services of the system-vms for the admin module to administrate, excluding any dynamic VMs such as app-vm. Expects a space separated list. Must be a of type ‘service’, e.g., ‘microvm@net-vm.service’.

Type: list of string

Default:

[ ]

Example:

services = ["microvm@net-vm.service"];

givc.admin.tls

TLS options for gRPC connections. It is enabled by default to discourage unprotected connections, and requires paths to certificates and key being set. To disable it use tls.enable = false;.

Caution It is recommended to use a global TLS flag to avoid inconsistent configurations that will result in connection errors.

Type: submodule

Default:

tls = {
  enable = true;
  caCertPath = "/etc/givc/ca-cert.pem";
  certPath = /etc/givc/cert.pem";
  keyPath = "/etc/givc/key.pem";
};

Example:

tls = {
  enable = true;
  caCertPath = "/etc/ssl/certs/ca-certificates.crt";
  certPath = "/etc/ssl/certs/server.crt";
  keyPath = "/etc/ssl/private/server.key";
};

givc.admin.tls.enable

Enable the TLS module. Defaults to ‘true’ and should only be disabled for debugging.

Type: boolean

Default:

true

givc.admin.tls.caCertPath

Path to the CA certificate file.

Type: string

Default:

"/etc/givc/ca-cert.pem"

givc.admin.tls.certPath

Path to the service certificate file.

Type: string

Default:

"/etc/givc/cert.pem"

givc.admin.tls.keyPath

Path to the service key file.

Type: string

Default:

"/etc/givc/key.pem"