Configuration¶

Gitfeed reads a per-instance YAML config file. The default path on a deployed box is /etc/pdns-pf/oxfeed-gitfeed/<instance>.yml, where <instance> matches the systemd template instance name. A commented template with every option is shipped as /etc/pdns-pf/oxfeed-gitfeed/example.yml.

Environment variables in YAML values are only expanded when the service is started with -expand-env. With expansion enabled you can write auth_http_password: "${GITFEED_TOKEN}" and supply the variable through the unit's environment file. The HTTP password is also picked up from the GITFEED_HTTP_PASSWORD environment variable directly, without -expand-env.

-strict rejects unknown YAML fields instead of silently ignoring them. Recommended for new deployments — see the shipped example caveats below.

Top-level structure¶

Parameter	Type	Default	Description
`run_once`	`boolean`	depends	Exit after a single update. Defaults to `true` without `-config` and `false` when a config file is loaded. The `-w` flag also forces `false`.
`git`	`Git`	—	Git source: where the repo lives, how to authenticate, how often to poll. Required.
`feed`	`Feed`	—	Where the feed is written. Required.
`http`	`HTTP`	`{}`	Status / metrics HTTP server. Disabled if `address` is empty.
`log`	`Log`	see section	Log format and level.

Deprecation policy¶

No fields have been deprecated or removed as of the current release.

Shipped example caveats¶

The shipped /etc/pdns-pf/oxfeed-gitfeed/example.yml includes a feed.retry block and feed.prune_enabled / feed.prune_interval keys. The gitfeed binary does not read those fields — they exist on the OX Feed Command Source's config struct, not gitfeed's. Without -strict they are silently ignored. With -strict the service refuses to start.

The other field names in the example match what gitfeed reads. The example is reproduced verbatim below so you can compare it against the file on disk.

Full example config¶

Click to expand the shipped example config

# Example config file for the pdns-pf-oxfeed-gitfeed service
#
# To add a systemd service instance, you need to take these steps (replace SOMENAME):
#
#   cp /etc/pdns-pf/oxfeed-gitfeed/example.yml \
#      /etc/pdns-pf/oxfeed-gitfeed/SOMENAME.yml
#   ln -s /lib/systemd/system/pdns-pf-oxfeed-gitfeed@.service \
#         /etc/systemd/system/pdns-pf-oxfeed-gitfeed@SOMENAME.service
#

# By default we run as a service when a config file is used.
# Set this to true to only do a single run.
#run_once: false

# This configures where and how we access git.
git:
    # This is either a path to a local git clone, or a full remote path.
    # Examples:
    #  - Local: /some/local/path
    #  - HTTP:  https://github.com/foo/bar.git
    #  - SSH:   git@github.com:foo/bar.git  (must include the username)
    root: "/path/to/local/repo"

    # If set, gitfeed will continue to try to init and clone a remote,
    # logging errors if it fails.
    # By default, the command will exit with an error.
    #retry_clone: false

    # Relative path to CSV file within the git repo
    file_path: example/feed.csv

    # Relative path to CSV file with codes mapping within the git repo.
    # This is optional and used to generate feed-codes.json.
    codes_csv_file_path: example/codes.csv
    # If you already have it in JSON form, use this instead:
    #codes_json_file_path: example/codes.json

    # Time between local git HEAD checks in watch mode (only for local repositories)
    #check_interval: 5s

    # Time between git remote fetches in watch mode (only for remote repositories)
    #fetch_interval: 5m

    # HTTP authentication
    # Only set these if you need HTTP Basic authentication to access git
    #auth_http_username: ""
    #auth_http_password: ""

    # Custom SSH key authentication
    # Only set these if you want to use a specific SSH identity key file for authentication,
    # for example a special deployment key.
    # By default we automatically use your configuration in ~/.ssh/ and any running ssh-agent.
    #auth_ssh_identity_file: "/path/to/deployment.key"
    #auth_ssh_identity_passphrase: ""
    #auth_ssh_identity_username: "someuser"  # should not be needed
    #auth_ssh_accept_any_host_key: false     # setting this disables host key checks (insecure)

    # If set to true, we try to start from last HEAD. This makes the startup faster, but it
    # will not repair missing files.
    # If kept as false (default), missing files will be written again.
    #incremental: false

    # You can use an external command to provide the data for feeds, with
    # gitfeed automatically committing changes it to a local git repository.
    # This is only allowed in combination with local 'root's.
    #command_source:
    #  command: some-command-source --wait
    #  interval: 5s

# Configures where and how the feed directory with feed.json is written
feed:
    # Path where the feed is saved to.
    # This is equivalent to `simpleblob://fs?root_path=/tmp/feed`
    # or `file:///tmp/feed`.
    #root: /tmp/feed

    # Make every code have its own namespace.
    # WARNING: Changing this later will trigger a full feed UUID reset!
    #namespace_per_code: false

# The HTTP server exposes Prometheus /metrics and a status page
http:
    # Address to listen on. ":8910" listens on port 8910 on all interfaces.
    # Disabled by default.
    #address: ":9617"
    # Serve feed under /feed. Not for production use!
    #serve_feed: false

log:
    level: info       # options: trace, debug, info, warning, error, fatal
    format: human     # options: human, logfmt, json
    timestamp: short  # options: short, full, disable

`git`¶

The git section configures where the source repository lives, how to authenticate against it, and how often to look for changes.

Choosing a mode¶

A root containing : is treated as a remote URL and cloned into memory on startup. Both https://... and git@host:path URLs are recognised.
Any other root value is treated as a path to an existing local checkout — gitfeed does not clone for you in local mode.
The literal value :empty: creates an empty in-memory repository. This is for tests, not production.

The remote/local distinction governs which poll interval applies: check_interval is consulted in both modes (in-process HEAD polling), fetch_interval only fires for remote roots.

Mutual-exclusion rules¶

The service refuses to start when any of these combinations is set:

auth_http_* together with auth_ssh_* — pick one auth method.
Both codes_csv_file_path and codes_json_file_path — pick one format.
command_source.command with a remote root — the in-memory clone is never pushed back to the remote, so committing to it would be invisible to other consumers.
command_source.command with codes_csv_file_path — the command source contract emits a JSON codes file, so codes_json_file_path is required.

Auth¶

The two authentication methods are documented under Architecture → Authentication. Set the HTTP fields or the SSH fields, never both. The passwords are masked in any config dump logged at startup or printed via -config-supplied -strict errors.

Warning

auth_ssh_accept_any_host_key: true disables host key checking and is vulnerable to MITM attacks. Use it only for one-shot debugging of an unknown host, never in production.

Fields¶

Parameter	Type	Default	Description
`root`	`string`	—	Required. Local path, http(s) URL, or `user@host:path` SSH URL. See Choosing a mode.
`file_path`	`string`	—	Required. Path within the repo to the watched CSV file.
`codes_csv_file_path`	`string`	—	Optional. Path within the repo to a CSV codes mapping. Mutex with `codes_json_file_path`.
`codes_json_file_path`	`string`	—	Optional. Path within the repo to a JSON codes mapping. Required when `command_source.command` is set.
`auth_http_username`	`string`	—	HTTP Basic username for fetching from `root`. Mutex with `auth_ssh_*`.
`auth_http_password`	`string`	—	HTTP Basic password. Masked in YAML dumps. Also accepted via `GITFEED_HTTP_PASSWORD`.
`auth_ssh_identity_file`	`string`	—	Path to an SSH private key file (unencrypted unless `auth_ssh_identity_passphrase` is set).
`auth_ssh_identity_username`	`string`	—	Override the SSH username; defaults to the prefix before `@` in `root`.
`auth_ssh_identity_passphrase`	`string`	—	Passphrase for the SSH key. Masked in YAML dumps.
`auth_ssh_accept_any_host_key`	`boolean`	`false`	Disables SSH host key verification. Insecure.
`retry_clone`	`boolean`	`false`	If the initial clone fails, sleep 10 s and retry instead of exiting.
`check_interval`	`go: Duration`	`5s`	Time between in-process HEAD checks. Minimum `1s`.
`fetch_interval`	`go: Duration`	`5m`	Time between git remote fetches. Minimum `5s`. Remote roots only.
`incremental`	`boolean`	`false`	Start from the last `git_head` in `feed.json` if it is still reachable. See Architecture → Incremental startup.
`command_source`	`CommandSource`	`{interval: 60s}`	Optional external command that drives commits. See Architecture → Command-source overlay.

`git.command_source`¶

Run an external command that supplies feed data; gitfeed commits the result to the local repo on every accepted run. See Architecture → Command-source contract for what the command must emit.

Parameter	Type	Default	Description
`command`	`string`	—	Shell command executed via `/bin/sh -c`. Empty disables the overlay.
`interval`	`go: Duration`	`60s`	Time between command runs. Minimum `100ms`.

Example, using a script that blocks until source data changes:

git:
  root: /var/lib/pdns-pf-oxfeed-gitfeed/repo
  file_path: feed.csv
  codes_json_file_path: feed-codes.json
  command_source:
    command: /usr/local/bin/dump-admin-feed --wait
    interval: 5s

`feed`¶

Where the feed tree is written.

Parameter	Type	Default	Description
`root`	`string` / `Root`	—	Required. Storage destination for the feed tree.
`namespace_per_code`	`boolean`	`false`	Place each classification code in its own LMDB namespace on downstream clients.

`feed.root`¶

The simpleblob storage where feed.json and the compressed snapshot / delta files are written. Accepts either a URI / path string or a struct.

String form (recommended):

feed:
  root: /var/lib/pdns-pf-oxfeed-gitfeed/feeds/my-feed

A bare filesystem path is equivalent to file:///path and to simpleblob://fs?root_path=/path. Other supported schemes are s3://... and memory://.

Struct form, for backends that need extra options:

feed:
  root:
    type: fs        # one of "fs", "memory", "s3"
    options:
      root_path: /var/lib/pdns-pf-oxfeed-gitfeed/feeds/my-feed

See simpleblob/backends/fs and simpleblob/backends/s3 for backend-specific options. The -o CLI flag overrides this field at startup.

`feed.namespace_per_code`¶

When true, every classification code gets its own LMDB namespace on downstream clients. This is required for domain-list-style feeds where the same domain may carry different code sets per tenant.

Warning

Changing namespace_per_code after a feed has been written triggers a full feed UUID reset, which forces every downstream client to re-snap from scratch. Decide this value once per feed and leave it alone.

`http`¶

The HTTP server bound to this address exposes a status page, Prometheus metrics, healthz, and pprof. Disabled when address is empty.

Parameter	Type	Default	Description
`address`	`string`	—	Bind address in `host:port` form (for example `:9617`).
`serve_feed`	`boolean`	`false`	Expose the feed tree under `/feed/`. See warning.

-http-addr and -http-serve-feed on the command line override these fields.

Warning

serve_feed is for development and one-shot testing only. The embedded HTTP server has no ETag support, no auth, and no rate limiting — it is not safe to expose to filter clients. In production, write the feed to a directory and front it with a proper static HTTP server (Caddy or nginx).

`log`¶

Parameter	Type	Default	Description
`level`	`string`	`info`	One of `trace`, `debug`, `info`, `warning`, `error`, `fatal`.
`format`	`string`	`human`	One of `human`, `logfmt`, `json`.
`timestamp`	`string`	`short`	One of `short`, `full`, `disable`.
`utc`	`boolean`	`true`	Log timestamps in UTC.

-log-level, -log-format, -log-timestamp, and -debug on the command line override the matching fields.

Configuration¶

Top-level structure¶

Deprecation policy¶

Shipped example caveats¶

Full example config¶

git¶

Choosing a mode¶

Mutual-exclusion rules¶

Auth¶

Fields¶

git.command_source¶

feed¶

feed.root¶

feed.namespace_per_code¶

http¶

log¶

`git`¶

`git.command_source`¶

`feed`¶

`feed.root`¶

`feed.namespace_per_code`¶

`http`¶

`log`¶