Carbonio Configd

https://github.com/zextras/carbonio-configd
Admin
A high-performance configuration daemon for Carbonio written in Go that manages service...
Tokens:13,574
Snippets:171
Trust Score:9.7
License:AGPL-3.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install pre-commit hooks

Source: https://github.com/zextras/carbonio-configd/blob/devel/CONTRIBUTING.md

Run this command to initialize the pre-commit hooks in your local repository.

```bash
pre-commit install
```

--------------------------------

### Retrieve Global Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches the global configuration settings from LDAP. This example specifically retrieves the 'zimbraDefaultDomainName'.

```go
// Get global configuration (cn=config,cn=zimbra)
globalConfig, err := client.GetGlobalConfig()
fmt.Println("Global config:", globalConfig["zimbraDefaultDomainName"])
```

--------------------------------

### Analyze CPU Profile

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Use the Go toolchain to analyze the generated CPU profile. This command starts an HTTP server for interactive analysis.

```bash
go tool pprof -http=:8080 cpu.prof
```

--------------------------------

### Build carbonio-configd Binary

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Build the main binary for the carbonio-configd daemon. Ensure Go 1.24+ and make are installed.

```bash
make build
```

--------------------------------

### Retrieve Version Information

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Displays Carbonio release and installed package versions.

```bash
# Show Carbonio release version
configd release

# Show installed package versions
configd release --packages
```

--------------------------------

### Retrieve Server Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches the configuration for a specific server identified by its hostname. This example retrieves 'zimbraServiceHostname'.

```go
// Get server configuration
serverConfig, err := client.GetServerConfig("mail.example.com")
fmt.Println("Server:", serverConfig["zimbraServiceHostname"])
```

--------------------------------

### Analyze Heap Profile

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Use the Go toolchain to analyze the generated memory (heap) profile. This command starts an HTTP server for interactive analysis.

```bash
go tool pprof -http=:8081 mem.prof
```

--------------------------------

### Retrieve All Servers with Attributes

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches all servers along with their attributes using a batch query. This example prints the 'zimbraServiceEnabled' attribute for each server.

```go
// Get all servers with full attributes (batch query)
serversWithAttrs, err := client.GetAllServersWithAttributes()
for hostname, attrs := range serversWithAttrs {
    fmt.Printf("%s: %s\n", hostname, attrs["zimbraServiceEnabled"])
}
```

--------------------------------

### Define variable interpolation in localconfig.xml

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/localconfig.md

Example of using ${key} syntax within an XML configuration value.

```xml
<key name="zimbra_log_directory">
  <value>${zimbra_home}/log</value>
</key>
```

--------------------------------

### Version Information

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Display Carbonio release and installed package versions.

```APIDOC
## Version Information

Displays Carbonio release and package versions.

### Show Carbonio Release Version

```bash
configd release
```

**Output:**
```
Carbonio Release 24.12.0
```

### Show Installed Package Versions

```bash
configd release --packages
```

**Output:**
```
Carbonio Release 24.12.0

Installed packages:
carbonio-configd 1.0.0-1
carbonio-core 24.12.0-1
...
```
```

--------------------------------

### Iterate over LDAP servers with !{explode server(serviceName)}

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/proxy-templates.md

Use this directive to generate configuration blocks for each server where the specified service is enabled. Comment lines starting with # are ignored during processing.

```nginx
!{explode server(mailbox)}
# skipped comment
    server ${server_hostname}:7071;

# Output (2 mailbox servers)
    server mailbox1.example.com:7071;
    server mailbox2.example.com:7071;
```

--------------------------------

### Manage carbonio-configd Service with systemd

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Control the carbonio-configd daemon using systemd. This includes starting, checking status, and reloading the service. Reloading triggers a re-evaluation of configurations.

```bash
systemctl start carbonio-configd.service
```

```bash
systemctl status carbonio-configd.service
```

```bash
systemctl reload carbonio-configd.service   # SIGHUP — re-evaluate configs
```

--------------------------------

### Perform Generic LDAP Search

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Executes a generic LDAP search query with specified base DN, filter, attributes, and scope. This example searches for servers and retrieves their 'cn' and 'zimbraServiceEnabled' attributes.

```go
// Generic search
result, err := client.Search(
    "cn=servers,cn=zimbra",
    "(objectClass=zimbraServer)",
    []string{"cn", "zimbraServiceEnabled"},
    ldap.ScopeSingleLevel,
)
for _, entry := range result.Entries {
    fmt.Println(entry.GetAttributeValue("cn"))
}
```

--------------------------------

### Modify LDAP Attribute

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Modifies a specific attribute for a given LDAP entry identified by its DN. This example enables the 'mta' service for a server.

```go
// Modify an attribute
err = client.ModifyAttribute(
    "cn=mail.example.com,cn=servers,cn=zimbra",
    "zimbraServiceEnabled",
    "mta",
)
```

--------------------------------

### Retrieve Single LDAP Entry by DN

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches a single LDAP entry based on its Distinguished Name (DN) and specified attributes. This example retrieves the 'zimbraServiceEnabled' attribute for a server.

```go
// Get single entry by DN
entry, err := client.GetEntry(
    "cn=mail.example.com,cn=servers,cn=zimbra",
    []string{"zimbraServiceEnabled"},
)
```

--------------------------------

### Trigger Config Rewrite via Client Mode

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Send a REWRITE command to a running carbonio-configd daemon to trigger configuration updates for specified sections. This command exits after sending the command and does not start a daemon.

```bash
configd rewrite proxy mta
```

```bash
# Replaces: echo "REWRITE proxy mta" | netcat -w 120 localhost 7171
```

--------------------------------

### Enabler Variables for Conditional Nginx Configuration

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/proxy-templates.md

Use enabler variables `${VAR}` at the start of a line for conditional logic. If VAR is truthy, the line is kept and processed; if falsy, the line is commented out. The variable must be registered as 'ValueTypeEnabler'. Nested variables are substituted.

```nginx
# Template
    ${mail.imap.enabled}include mail.imap.conf;
    ${mail.pop3.enabled}include mail.pop3.conf;

# Output when imap enabled, pop3 disabled
    include mail.imap.conf;
    #include mail.pop3.conf;
```

--------------------------------

### Explode Directive for Domain-Specific Nginx Blocks

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/proxy-templates.md

The `!{explode domain(vhn)}` directive at the start of a template generates blocks per domain. It sets variables like `${vhn}`, `${vip}`, `${ssl.crt}`, and `${ssl.key}` for each domain. Domains with empty virtual hostnames are skipped.

```nginx
!{explode domain(vhn)}
```

--------------------------------

### Initialize Components

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Trigger configuration generation and service startup for specific components.

```bash
# Initialize MTA (postfix, saslauthd, LDAP transport maps)
configd init mta

# Initialize proxy (nginx reverse proxy configs)
configd init proxy

# Force reinitialization even if configs exist
configd init mta --force
```

--------------------------------

### Initialize LDAP Client with Connection Pooling

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Demonstrates how to create a new LDAP client instance with connection pooling and retry logic. Ensure all configuration parameters are correctly set for your LDAP server.

```go
package main

import (
    "fmt"
    "github.com/zextras/carbonio-configd/internal/ldap"
    "time"
)

func main() {
    // Create LDAP client with connection pooling
    client, err := ldap.NewClient(&ldap.ClientConfig{
        URL:           "ldap://localhost:389",
        BindDN:        "uid=zimbra,cn=admins,cn=zimbra",
        Password:      "secret",
        BaseDN:        "cn=zimbra",        // defaults to "cn=zimbra"
        PoolSize:      5,                  // connection pool size
        MaxRetries:    3,                  // retry attempts
        RetryDelay:    100 * time.Millisecond,
        MaxRetryDelay: 5 * time.Second,
        StartTLS:      true,               // upgrade ldap:// to TLS
    })
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // ... rest of the code ...
}
```

--------------------------------

### Show Config File Path

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Use the '-p' flag to display the path to the local configuration file.

```bash
# Show config file path
configd localconfig -p
```

--------------------------------

### Manage Services with systemd Integration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Demonstrates service lifecycle management, dependency handling, and status discovery using the services package.

```go
package main

import (
    "context"
    "github.com/zextras/carbonio-configd/internal/services"
)

func main() {
    ctx := context.Background()

    // Create service manager
    sm := services.NewServiceManager()

    // Enable systemd mode (uses systemctl with polkit)
    sm.SetUseSystemd(true)

    // Control a service
    err := sm.ControlProcess(ctx, "mta", services.ActionRestart)
    err = sm.ControlProcess(ctx, "proxy", services.ActionStop)
    err = sm.ControlProcess(ctx, "mailbox", services.ActionStart)
    err = sm.ControlProcess(ctx, "ldap", services.ActionStatus)

    // Check if service is running
    running, err := sm.IsRunning(ctx, "mta")

    // Queue services for restart
    sm.AddRestart(ctx, "mta")
    sm.AddRestart(ctx, "proxy")

    // Process all queued restarts with dependency ordering
    configLookup := func(key string) string {
        // Return config values like SERVICE_MTA, SERVICE_PROXY
        return "enabled"
    }
    err = sm.ProcessRestarts(ctx, configLookup)

    // Get pending restarts
    pending := sm.GetPendingRestarts()

    // Clear all pending restarts
    sm.ClearRestarts(ctx)

    // Disable restarts (dry-run mode)
    sm.DisableRestarts = true

    // Set service dependencies
    sm.SetDependencies(ctx, map[string][]string{
        "mta": {"amavis", "antispam", "antivirus"},
    })

    // Lookup service definition from registry
    def := services.LookupService("mta")
    fmt.Printf("Service: %s, Units: %v\n", def.DisplayName, def.SystemdUnits)
    // Output: Service: mta, Units: [carbonio-postfix.service]

    // Get all service names in start order
    allServices := services.AllServiceNames()

    // High-level service operations
    err = services.ServiceStart(ctx, "mta")
    err = services.ServiceStop(ctx, "proxy")
    err = services.ServiceRestart(ctx, "mailbox")
    err = services.ServiceReload(ctx, "mta")
    running, err = services.ServiceStatus(ctx, "ldap")

    // List all services with status
    infos := services.ServiceListStatus(ctx)
    for _, info := range infos {
        fmt.Printf("%s: running=%v\n", info.DisplayName, info.Running)
    }

    // Discover LDAP-enabled services
    enabled, err := services.DiscoverEnabledServices(ctx)
    // enabled: ["ldap", "mailbox", "mta", "proxy"]

    // Check if LDAP is local
    if services.IsLDAPLocal() {
        fmt.Println("LDAP server is on this host")
    }
}
```

--------------------------------

### Retrieve All Servers

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches a list of all configured servers. The output will contain the hostname of each server.

```go
// Get all servers
servers, err := client.GetAllServers()
for _, server := range servers {
    fmt.Println("Server:", server)
}
```

--------------------------------

### Build Configd with Profiling Support

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Build the configd binary with profiling enabled using the 'profiling' build tag. This is necessary to use profiling flags.

```bash
go build -tags profiling ./cmd/configd
```

--------------------------------

### Run Configd with Profiling Flags

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Execute the profiled configd binary to generate CPU and memory profiles for a single configuration cycle. Ensure to run as the correct user.

```bash
sudo -u zextras ./configd-prof --once --cpuprofile cpu.prof --memprofile mem.prof
```

--------------------------------

### Retrieve Domain Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches the configuration settings for a specific domain.

```go
// Get domain configuration
domainConfig, err := client.GetDomain("example.com")
```

--------------------------------

### Orchestrate Services

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Control all enabled services in dependency order.

```bash
# Start all enabled services
configd control start

# Stop all services (reverse order)
configd control stop

# Restart all services
configd control restart

# Show status of all services
configd control status

# Execute on remote host via SSH
configd control --host remote-server start
```

--------------------------------

### Orchestrate Configuration Changes

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Handles configuration loading, change detection via MD5 fingerprinting, and execution of rewrites and service restarts.

```go
package main

import (
    "context"
    "github.com/zextras/carbonio-configd/internal/cache"
    "github.com/zextras/carbonio-configd/internal/config"
    "github.com/zextras/carbonio-configd/internal/configmgr"
    "github.com/zextras/carbonio-configd/internal/ldap"
    "github.com/zextras/carbonio-configd/internal/state"
)

func main() {
    ctx := context.Background()

    // Initialize configuration
    mainCfg := config.NewConfig()
    appState := state.NewState()
    ldapClient := &ldap.Ldap{} // Initialize with actual LDAP connection
    cacheInstance := cache.New(ctx, false)

    // Create config manager
    cm := configmgr.NewConfigManager(ctx, mainCfg, appState, ldapClient, cacheInstance)

    // Load all configurations concurrently (localconfig, global, server, misc)
    err := cm.LoadAllConfigs(ctx)
    if err != nil {
        panic(err)
    }

    // Parse MTA configuration file
    err = cm.ParseMtaConfig(ctx, "/opt/zextras/conf/zmconfigd.cf")

    // Compare keys to detect changes (MD5 fingerprinting)
    err = cm.CompareKeys(ctx)

    // Compile actions based on detected changes
    cm.CompileActions(ctx)

    // Execute configuration rewrites
    err = cm.DoConfigRewrites(ctx)

    // Execute service restarts
    cm.DoRestarts(ctx)
}
```

--------------------------------

### Retrieve All Domains

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches a list of all configured domains within the Carbonio environment.

```go
// Get all domains
domains, err := client.GetAllDomains()
```

--------------------------------

### Analyze Execution Trace

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Use the Go toolchain to analyze the generated execution trace. This opens a web-based viewer for detailed trace information.

```bash
go tool trace trace.out
```

--------------------------------

### Run Configd with Execution Trace

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Execute the profiled configd binary to generate an execution trace for a single configuration cycle. This trace can help identify scheduling and blocking issues.

```bash
sudo -u zextras ./configd-prof --once --trace trace.out
```

--------------------------------

### Run project tests and linters

Source: https://github.com/zextras/carbonio-configd/blob/devel/CONTRIBUTING.md

Execute these Makefile commands to verify code quality and test functionality.

```makefile
# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run linter
make lint

# Run tests with race detector
make test-race
```

--------------------------------

### Format LDAP Configuration as zmprov Output

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Formats a map of LDAP attributes into a zmprov-style string output. Useful for displaying configuration in a human-readable format.

```go
// Format config as zmprov-style output
output := ldap.FormatAsZmprovOutput(serverConfig)
fmt.Print(output)
// Output:
// zimbraServiceHostname: mail.example.com
// zimbraServiceEnabled: ldap
// zimbraServiceEnabled: mailbox
// ...
}
```

--------------------------------

### Access Local Configuration with Go

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Provides programmatic access to localconfig.xml for reading, editing, and managing configuration keys.

```go
package main

import (
    "fmt"
    "github.com/zextras/carbonio-configd/internal/localconfig"
)

func main() {
    // Load and resolve all configuration with defaults and variable interpolation
    config, err := localconfig.LoadResolvedConfig()
    if err != nil {
        panic(err)
    }

    // Access configuration values
    ldapURL := config["ldap_url"]
    ldapPort := config["ldap_port"]
    fmt.Printf("LDAP: %s:%s\n", ldapURL, ldapPort)

    // Load from custom path
    config, err = localconfig.LoadResolvedConfigFromFile("/custom/path/localconfig.xml")

    // Load raw config without defaults/interpolation
    rawConfig, err := localconfig.LoadLocalConfig()

    // Mask passwords in config map
    maskedConfig := localconfig.MaskPasswords(config)

    // Format as key=value output
    output := localconfig.FormatAsKeyValue(config)
    fmt.Print(output)

    // Edit configuration
    err = localconfig.SetKey("/opt/zextras/conf/localconfig.xml", "smtp_port", "587")

    // Remove a key
    err = localconfig.RemoveKey("/opt/zextras/conf/localconfig.xml", "custom_key")

    // Generate random password
    password, err := localconfig.GeneratePassword(64)
}
```

--------------------------------

### Use Localconfig Subcommand for Key Management

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Interact with local configuration using the `configd localconfig` subcommand, a replacement for the Java `zmlocalconfig` CLI. It reads `localconfig.xml`, applies defaults, and resolves variables.

```bash
eval "$(configd localconfig -q -m export)"
```

```bash
configd localconfig -k mailboxd_java_options -k ldap_port
```

--------------------------------

### Trigger Configuration Rewrite

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Regenerates configuration sections via network commands or Go code.

```bash
# Rewrite specific sections
echo "REWRITE proxy mta" | nc localhost 7171

# Rewrite all sections
echo "REWRITE" | nc localhost 7171
```

```go
conn, _ := net.Dial("tcp", "localhost:7171")
fmt.Fprintln(conn, "REWRITE proxy")
response, _ := bufio.NewReader(conn).ReadString('\n')
// response: "SUCCESS REWRITES COMPLETE\n"
```

--------------------------------

### Retrieve Enabled Services for a Server

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches the list of services that are currently enabled for a given server hostname.

```go
// Get enabled services for a server
services, err := client.GetEnabledServices("mail.example.com")
// services: ["ldap", "mailbox", "mta", "proxy", ...]
```

--------------------------------

### Implement TCP Control Interface

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Sets up a threaded TCP server to handle configuration rewrite requests and status checks.

```go
package main

import (
    "context"
    "github.com/zextras/carbonio-configd/internal/network"
)

// Implement ActionTrigger interface
type MyTrigger struct{}

func (t *MyTrigger) TriggerRewrite(configs []string) {
    // Handle rewrite request for specified configs
    for _, cfg := range configs {
        fmt.Println("Rewriting:", cfg)
    }
}

func main() {
    ctx := context.Background()

    trigger := &MyTrigger{}
    handler := &network.ConfigdRequestHandler{ActionTrigger: trigger}

    // Create server on localhost:7171 (IPv4)
    server := network.NewThreadedStreamServer("127.0.0.1", 7171, false, handler)

    // Start accepting connections (non-blocking)
    err := server.ServeForever(ctx)
    if err != nil {
        panic(err)
    }

    // Server handles these commands:
    // - STATUS -> "SUCCESS ACTIVE"
    // - REWRITE [sections...] -> "SUCCESS REWRITES COMPLETE"

    // Graceful shutdown
    server.Shutdown(ctx)
}
```

--------------------------------

### Run carbonio-configd Tests

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Execute the test suite for carbonio-configd to ensure code integrity. Requires a Go development environment.

```bash
make test
```

--------------------------------

### Retrieve All Domains with Attributes

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Fetches all domains along with their attributes using a single query.

```go
// Get all domains with attributes (single query)
domainsWithAttrs, err := client.GetAllDomainsWithAttributes()
```

--------------------------------

### CLI Command: localconfig

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Manages local configuration settings including retrieval, editing, and unsetting of keys.

```APIDOC
## CLI Command: localconfig

### Description
Manages local configuration settings. Allows retrieving values in various formats, editing keys, setting random passwords, and unsetting keys.

### Parameters
#### Flags
- **-m** (string) - Optional - Output mode: plain, shell, export, nokey, xml
- **-k** (string) - Optional - Key to retrieve (repeatable; omit for all keys)
- **-q** (boolean) - Optional - Quiet mode (suppress warnings)
- **-f** (string) - Optional - Path to localconfig.xml (default: /opt/zextras/conf/localconfig.xml)
- **-s** (boolean) - Optional - Show password values (default: masked)
- **-d** (boolean) - Optional - Show default values instead of current
- **-n** (boolean) - Optional - Show only keys changed from defaults
- **-x** (boolean) - Optional - Expand variables
- **-e** (string) - Optional - Edit: set key=value pairs
- **-u** (string) - Optional - Unset (remove) keys
- **-r** (boolean) - Optional - Set key to random password (use with -e)
- **-force** (boolean) - Optional - Allow editing dangerous keys
- **-p** (boolean) - Optional - Print config file path and exit

### Request Example
configd localconfig -m export -k zimbra_home

### Response
export zimbra_home='/opt/zextras';
```

--------------------------------

### Manage Proxy Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Generate and inspect nginx reverse proxy configurations.

```bash
# Generate nginx proxy configuration files (replaces zmproxyconfgen)
configd proxy gen

# Print assembled nginx configuration (replaces zmproxyconf)
configd proxy conf

# Print with file inclusion markers
configd proxy conf -m

# Print indented with no comments or empty lines
configd proxy conf -i -n -e
```

--------------------------------

### Manage Local Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Drop-in replacement for zmlocalconfig for reading and modifying localconfig.xml.

```bash
# Read all configuration keys (shell-eval format)
eval "$(configd localconfig -q -m export)"

# Query specific keys
configd localconfig -k mailboxd_java_options -k ldap_port

# Output modes: plain, shell, export, nokey, xml
configd localconfig -m export -k zimbra_home
# Output: export zimbra_home='/opt/zextras';

# Edit configuration keys
configd localconfig -e smtp_port=587

# Generate random password for a key
configd localconfig -e -r ldap_root_password

# Unset a key
configd localconfig -u custom_key

# Show config file path
configd localconfig -p
# Output: /opt/zextras/conf/localconfig.xml

# Show only keys changed from defaults
configd localconfig -n

# Show default values instead of current
configd localconfig -d

# Show password values (default: masked)
configd localconfig -s -k zimbra_ldap_password

# Edit dangerous keys (requires --force)
configd localconfig -e --force ldap_url=ldap://newserver:389
```

--------------------------------

### Rewrite Configuration Sections

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Force regeneration of configuration files without restarting services.

```bash
# Rewrite proxy and MTA configurations
configd rewrite proxy mta

# Rewrite all configurations
configd rewrite all

# Equivalent netcat command (legacy)
echo "REWRITE proxy mta" | netcat -w 120 localhost 7171
```

--------------------------------

### Go Package APIs - localconfig

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Provides direct access to Carbonio local configuration using the `localconfig` Go package.

```APIDOC
## Go Package APIs

### localconfig Package

Provides direct access to Carbonio local configuration by parsing `/opt/zextras/conf/localconfig.xml`.

```go
package main

import (
    "fmt"
    "github.com/zextras/carbonio-configd/internal/localconfig"
)

func main() {
    // Load and resolve all configuration with defaults and variable interpolation
    config, err := localconfig.LoadResolvedConfig()
    if err != nil {
        panic(err)
    }

    // Access configuration values
    ldapURL := config["ldap_url"]
    ldapPort := config["ldap_port"]
    fmt.Printf("LDAP: %s:%s\n", ldapURL, ldapPort)

    // Load from custom path
    config, err = localconfig.LoadResolvedConfigFromFile("/custom/path/localconfig.xml")

    // Load raw config without defaults/interpolation
    rawConfig, err := localconfig.LoadLocalConfig()

    // Mask passwords in config map
    maskedConfig := localconfig.MaskPasswords(config)

    // Format as key=value output
    output := localconfig.FormatAsKeyValue(config)
    fmt.Print(output)
    // Output:
    // ldap_url = ldap://localhost:389
    // ldap_port = 389
    // ...

    // Edit configuration
    err = localconfig.SetKey("/opt/zextras/conf/localconfig.xml", "smtp_port", "587")

    // Remove a key
    err = localconfig.RemoveKey("/opt/zextras/conf/localconfig.xml", "custom_key")

    // Generate random password
    password, err := localconfig.GeneratePassword(64)
}
```
```

--------------------------------

### Manage Proxy Protocols via CLI

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Commands to enable, disable, or check the status of proxy protocols.

```bash
configd proxy enable https
configd proxy disable pop3

# Show all protocol statuses
configd proxy status
```

--------------------------------

### Package carbonio-configd for Distributions

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Build distribution-specific packages for carbonio-configd using the 'yap' tool. Specify the target distribution and version.

```bash
make build TARGET=ubuntu-noble
```

```bash
make build TARGET=rocky-9
```

--------------------------------

### Manage Carbonio Services

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Operations for individual service lifecycle management.

```bash
# List all services with status
configd service list

# Start a service
configd service start mta

# Start service without config regeneration
configd service start mta --no-rewrite

# Stop a service
configd service stop proxy

# Restart a service
configd service restart mailbox

# Reload a service (graceful)
configd service reload mta

# Check service status
configd service status ldap
# Output:
# directory server is running.
#   PID: 12345
#   Since: Wed 2024-01-15 10:30:00 UTC
#   Memory: 52428800
```

--------------------------------

### Export Configuration Key

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Use the 'export' mode to retrieve the value of a specific configuration key. This is useful for scripting or understanding current settings.

```bash
# Output modes: plain, shell, export, nokey, xml
configd localconfig -m export -k zimbra_home
# Output: export zimbra_home='/opt/zextras';
```

--------------------------------

### Manage Carbonio Configd Daemon

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Commands for controlling the daemon via systemd or direct execution.

```bash
# Start the configuration daemon via systemd
systemctl start carbonio-configd.service

# Check daemon status
systemctl status carbonio-configd.service

# Trigger a configuration reload (SIGHUP)
systemctl reload carbonio-configd.service

# Run in dry-run mode (no service restarts)
configd --disable-restarts
```

--------------------------------

### Convert MTA Restart to Reload Action

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/restart-behavior.md

This Go code snippet shows how restart requests for the 'mta' service are converted to 'reload' actions. This ensures a graceful reload of Postfix instead of a disruptive full restart.

```go
if service == serviceMTA && action == ActionRestart {
    actionStr = actionReload
}
```

--------------------------------

### Implement systemd notifications in Go

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Use the sdnotify package to communicate with systemd. The notifier automatically detects the NOTIFY_SOCKET environment variable.

```go
package main

import (
    "github.com/zextras/carbonio-configd/internal/sdnotify"
)

func main() {
    // Create notifier (reads NOTIFY_SOCKET env var)
    notifier, err := sdnotify.New()
    if err != nil {
        // No systemd socket available - notifier is a no-op
    }

    // Signal service is ready
    err = notifier.Ready()

    // Send status message
    err = notifier.Status("Processing %d items", 42)

    // Send watchdog ping
    err = notifier.WatchdogPing()

    // Check if notifier is enabled
    if notifier.Enabled() {
        fmt.Println("Running under systemd")
    }

    // Check if watchdog is enabled and get interval
    if interval, ok := sdnotify.WatchdogEnabled(); ok {
        fmt.Printf("Watchdog interval: %v\n", interval)
        // Ping at half the interval
        pingInterval := interval / 2
    }
}
```

--------------------------------

### Parallel Config Rewrites with Semaphore

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/performance.md

Implement concurrent configuration file rewrites using a buffered channel as a semaphore to limit the number of parallel operations. The 'maxConcurrent' value is tuned for I/O contention.

```go
maxConcurrent := 4  // Tuned for balance between parallelism and I/O contention
semaphore := make(chan struct{}, maxConcurrent)

for filePath, rewriteEntry := range rewrites {
    semaphore <- struct{}{}
    go func(...) {
        defer func() { <-semaphore }()
        cm.processRewrite(ctx, fp, re)
    }(...)
}
wg.Wait()
```

--------------------------------

### Proxy Protocol Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Enable, disable, or check the status of proxy protocols.

```APIDOC
## Proxy Protocol Configuration

Manages the enabling and disabling of various proxy protocols.

### Enable Proxy Protocol

```bash
configd proxy enable <protocol>
```

### Disable Proxy Protocol

```bash
configd proxy disable <protocol>
```

### Show Proxy Protocol Status

```bash
configd proxy status
```

**Example Output:**
```
Proxy Protocol Status:
  http     enabled
  https    enabled
  imap     enabled
  imaps    enabled
  pop3     disabled
  pop3s    disabled
```
```

--------------------------------

### Simple Variable Substitution in Nginx Templates

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/proxy-templates.md

Use simple substitution `${VAR}` to replace tokens with variable values. If a variable is undefined, it's replaced with an empty string. This is useful for dynamic configuration values.

```nginx
# Template
server_name ${vhn};
proxy_pass  http://127.0.0.1:${mail.imap.port};

# Output (vhn = "mail.example.com", mail.imap.port = "7143")
server_name mail.example.com;
proxy_pass  http://127.0.0.1:7143;
```

--------------------------------

### Configd Localconfig Flags

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Reference for the available flags for the configd localconfig command, detailing their purpose and usage.

```bash
Flags:

-m mode          Output mode: plain, shell, export, nokey, xml
-k key           Key to retrieve (repeatable; omit for all keys)
-q               Quiet mode (suppress warnings)
-f path          Path to localconfig.xml (default: /opt/zextras/localconfig.xml)
-s               Show password values (default: masked)
-d               Show default values instead of current
-n               Show only keys changed from defaults
-x               Expand variables (accepted for compatibility, always on)
-e               Edit: set key=value pairs
-u               Unset (remove) keys
-r               Set key to random password (use with -e)
-force           Allow editing dangerous keys
-p               Print config file path and exit
```

--------------------------------

### Edit Configuration Key

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Use the '-e' flag to edit configuration keys. Values can be set directly or a random password can be generated using '-r'.

```bash
# Edit keys
configd localconfig -e smtp_port=587
configd localconfig -e -r ldap_root_password    # random password
```

--------------------------------

### Check Daemon Status

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Verifies if the configuration daemon is active using netcat or the CLI client.

```bash
# Using netcat
echo "STATUS" | nc localhost 7171

# Using the CLI client
configd rewrite
```

--------------------------------

### Unset Configuration Key

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Use the '-u' flag to remove a specific configuration key from the settings.

```bash
# Unset a key
configd localconfig -u custom_key
```

--------------------------------

### Network Protocol API - STATUS Command

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Check if the configd daemon is active and responding using the STATUS command.

```APIDOC
## Network Protocol API

The daemon listens on port 7171 (configurable via `zmconfigd_listen_port`) and accepts newline-terminated commands.

### STATUS Command

Check if the daemon is active and responding.

#### Using netcat

```bash
echo "STATUS" | nc localhost 7171
```

**Response:**
```
SUCCESS ACTIVE
```

#### Using the CLI client

```bash
configd rewrite  # Will fail with clear error if daemon unavailable
```
```

--------------------------------

### Explode Directive with Client Certificate Filter

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/proxy-templates.md

Use `!{explode domain(vhn, sso)}` to generate blocks per domain, further filtering for domains where `zimbraClientCertMode` is not empty or 'off'. This is for templates requiring client-certificate authentication.

```nginx
!{explode domain(vhn, sso)}
```

--------------------------------

### Network Protocol API - REWRITE Command

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Trigger configuration regeneration for specific sections or all sections using the REWRITE command.

```APIDOC
### REWRITE Command

Trigger configuration regeneration for specific sections or all sections.

#### Rewrite Specific Sections

```bash
echo "REWRITE proxy mta" | nc localhost 7171
```

**Response:**
```
SUCCESS REWRITES COMPLETE
```

#### Rewrite All Sections

```bash
echo "REWRITE" | nc localhost 7171
```

**Response:**
```
SUCCESS REWRITES COMPLETE
```

#### Programmatic example (Go)

```go
conn, _ := net.Dial("tcp", "localhost:7171")
fmt.Fprintln(conn, "REWRITE proxy")
response, _ := bufio.NewReader(conn).ReadString('\n')
// response: "SUCCESS REWRITES COMPLETE\n"
```
```

--------------------------------

### TLS/Mail Mode Configuration

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Configure Carbonio mail mode and rewrite TLS-related configurations.

```APIDOC
## TLS/Mail Mode Configuration

Manages Carbonio mail mode (replacement for legacy `zmtlsctl`). Sets `zimbraMailMode` on the server and rewrites affected configs.

### Set Mail Mode

```bash
# Set mail mode to HTTPS only
configd tls https

# Set mail mode with proxy validation bypass
configd tls mixed --force
```

**Valid modes:** `both`, `http`, `https`, `mixed`, `redirect`

### Rewrite TLS Configurations

```bash
# Rewrite TLS-related configs without changing mode
configd tls
```
```

--------------------------------

### carbonio-configd Profiling Flags

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Profiling flags for carbonio-configd, available when built with the 'profiling' tag. These flags allow detailed performance analysis.

```bash
--once               Run one config cycle and exit
```

```bash
--cpuprofile file    Write CPU profile to file
```

```bash
--memprofile file    Write memory profile to file
```

```bash
--trace file         Write execution trace to file
```

```bash
--profile-duration s Profile for s seconds (0 = entire run)
```

--------------------------------

### Skip Restarts in REWRITE Command Cycle

Source: https://github.com/zextras/carbonio-configd/blob/devel/docs/restart-behavior.md

This Go code snippet demonstrates the condition under which service restarts are skipped during a REWRITE command cycle. It ensures that config files are updated without affecting running services.

```go
if firstRun || len(forcedConfig) > 0 || len(requestedConfigs) > 0 {
    return  // skip restarts
}
```

--------------------------------

### Configure TLS Mail Mode

Source: https://context7.com/zextras/carbonio-configd/llms.txt

Sets the zimbraMailMode on the server and triggers configuration rewrites.

```bash
# Set mail mode to HTTPS only
configd tls https

# Set mail mode with proxy validation bypass
configd tls mixed --force

# Valid modes: both, http, https, mixed, redirect

# Rewrite TLS-related configs without changing mode
configd tls
```

--------------------------------

### Bypass pre-commit hooks

Source: https://github.com/zextras/carbonio-configd/blob/devel/CONTRIBUTING.md

Use this command to commit changes without triggering the pre-commit hooks.

```bash
git commit --no-verify
```

--------------------------------

### Lint carbonio-configd Code

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Perform static analysis and linting on the carbonio-configd codebase to maintain code quality. This command checks for common errors and style issues.

```bash
make lint
```

--------------------------------

### Configure carbonio-configd Polling Interval

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Override the default polling interval for carbonio-configd using `zmconfigd_interval` in `localconfig.xml`. The daemon skips config loading during idle polls if no REWRITE events occurred.

```xml
<key name="zmconfigd_interval">
  <value>60</value>
</key>
```

--------------------------------

### carbonio-configd Daemon Flags

Source: https://github.com/zextras/carbonio-configd/blob/devel/README.md

Runtime flags for the carbonio-configd daemon. The `--disable-restarts` flag enables a dry-run mode without service restarts.

```bash
--disable-restarts   Dry-run mode (no service restarts)
```

```bash
--help, -h           Show help message
```
Tokens:
Raw