{"id":13587161,"url":"https://github.com/phyber/jail_exporter","last_synced_at":"2025-04-07T19:30:57.893Z","repository":{"id":37802517,"uuid":"136074320","full_name":"phyber/jail_exporter","owner":"phyber","description":"A Prometheus exporter for FreeBSD jail metrics","archived":false,"fork":false,"pushed_at":"2023-12-31T00:45:26.000Z","size":851,"stargazers_count":31,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-26T01:21:53.739Z","etag":null,"topics":["exporter","freebsd","jail","metrics","prometheus","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phyber.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-06-04T19:41:31.000Z","updated_at":"2024-03-28T16:22:31.000Z","dependencies_parsed_at":"2022-06-22T18:11:23.165Z","dependency_job_id":"31c05b91-8b52-471c-bfcb-4b977a7590cd","html_url":"https://github.com/phyber/jail_exporter","commit_stats":{"total_commits":594,"total_committers":4,"mean_commits":148.5,"dds":0.04882154882154888,"last_synced_commit":"7ce85041c92e5fde27473b6764ade097ac040442"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phyber%2Fjail_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phyber%2Fjail_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phyber%2Fjail_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phyber%2Fjail_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phyber","download_url":"https://codeload.github.com/phyber/jail_exporter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223290410,"owners_count":17120910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exporter","freebsd","jail","metrics","prometheus","rust"],"created_at":"2024-08-01T15:06:03.389Z","updated_at":"2024-11-06T05:31:18.736Z","avatar_url":"https://github.com/phyber.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Jail Exporter\n\n[![Build Status]](https://cirrus-ci.com/github/phyber/jail_exporter)\n\n## Description\n\nJail Exporter is a [Prometheus] exporter for [FreeBSD] jail metrics as reported\nby [`rctl(8)`].\n\nThe exporter is written in [Rust] and uses the [jail] and [rctl] crates to\ndiscover jails and obtain metrics.\n\n## Installation\n\n### `pkg(8)` and Ports\n\n`jail_exporter` is available in the FreeBSD ports tree as\n`sysutils/jail_exporter`. It can be installed by either the binary package with\n`pkg install jail_exporter`, or by compiling the package yourself in the ports\ntree.\n\n### Cargo Install\n\nThe crate is also available via [crates.io], and can be installed using the\n`cargo install` command. However, it is heavily recommended to install the\nexporter via `pkg(8)` or the ports tree.\n\n```shell\n$ cargo install jail_exporter\n```\n\nWhen installing via this method, you may want to move the installed binary to\n`/usr/local/sbin` and obtain an appropriate [`rc(8)`] to start the exporter on\nsystem boot. You can do this as follows:\n\n```shell\n# Performed as root.\n$ mv ~/.cargo/bin/jail_exporter /usr/local/sbin/\n$ chown root:wheel /usr/local/sbin/jail_exporter\n$ jail_exporter --rc-script | tee /usr/local/etc/rc.d/jail_exporter\n$ chmod 755 /usr/local/etc/rc.d/jail_exporter\n```\n\n### Enabling at System Boot\n\nYou can enable `jail_exporter` to start at system boot via [`rc.conf(5)`].\n\n```shell\n# Either edit /etc/rc.conf directly or use the following command\nsysrc jail_exporter_enable=YES\n```\n\n## Building\n\nAt a minimum, building Jail Exporter should require:\n\n  - Rust v1.80.1 (MSRV)\n  - Cargo\n\nA BSD [`make(1)`] Makefile is provided for convenience, if you already have\nRust and Cargo available, executing `make` will build a debug release of Jail\nExporter at `target/debug/jail_exporter`. `make release` will build a release\nversion at `target/release/jail_exporter`.\n\nIf you don't wish to use `make(1)`, the usual `cargo build` command should work\njust fine.\n\n## Configuration\n\nConfiguration can be performed either via command line arguments or environment\nvariables.  If both an environment variable and a command line argument are\nprovided for the same option, the configuration will be taken from the command\nline argument.\n\n### Command Line Arguments\n\nArgument               | Default          | Purpose\n-----------------------|------------------|--------\n`--output.file-path`   | N/A              | Output metrics to a file instead of running an HTTPd.\n`--rc-script`          | N/A              | Output an appropriate rc.d script\n`--web.auth-config`    | N/A              | HTTP Basic authentication configuration file.\n`--web.listen-address` | `127.0.0.1:9452` | Address on which to expose metrics and web interface.\n`--web.telemetry-path` | `/metrics`       | Path under which to expose metrics.\n\n### Environment variables\n\nVariable             | Equivalent Argument\n---------------------|--------------------\n`OUTPUT_FILE_PATH`   | `output.file-path`\n`WEB_AUTH_CONFIG  `  | `web.auth-config`\n`WEB_LISTEN_ADDRESS` | `web.listen-address`\n`WEB_TELEMETRY_PATH` | `web.telemetry-path`\n\n### HTTP Basic Authentication\n\nHTTP Basic Authentication is available when the crate is compiled with the\n`auth` feature. This feature is enabled by default.\n\nThe configuration file format is the same as specified in [`exporter-toolkit`].\n\n```yaml\n---\nbasic_auth_users:\n    username: 'bcrypt hashed secret'\n    another_user: 'bcrypt hashed secret'\n```\n\nIf no configuration is specified, or the configuration is specified but\ncontains no users, authentication will be disabled.\n\nWhile loading the configuration, usernames will be checked for compliance with\n[RFC7617]. If any invalid usernames are detected, `jail_exporter` will error\nout and refuse to start.\n\nUser passwords are [bcrypt] hashed secrets, which can be generated with the\n`bcrypt` subcommand if `jail_exporter` was compiled with the `bcrypt_cmd`\nfeature (enabled by default).\n\n```shell\n# Generate a password by specifying it on the CLI \n$ jail_exporter bcrypt foobar\nHash: $2b$12$kSOSps7NIQaEQi2CXb.Ll.qYQZ3pCK7NDWKUH7QvHzprUyLHL6tsq\n\n# Generate a password via an interactive prompt\n# The password will be prompted for and then confirmed\n$ jail_exporter bcrypt\nPassword: [hidden]\nHash: $2b$12$/5ghhZFShmhrq5W4tE1hnubk/xgGH0MmixxQeKwSGx0g7kjDFL2hq\n\n# Generate a random password\n# The random plaintext password will also be output.\n$ jail_exporter bcrypt --random\nPassword: TiFRz4rg6JHdRunnIFm2aB3uNa0OnlU7\nHash: $2b$12$dyK2iA1Yq1ToA9AWtjg96exmvLABj05DuB1V5a4haUOZvu2.Hvbo2\n```\n\nThe cost for the password hashing can be controlled with the `--cost` argument\nto the `bcrypt` subcommand and defaults to `12`. This default it taken from the\nbcrypt crate and should be tuned for the computer the hashing will be running\non, as this cost will be paid each time a connection is authenticated.\n\n## Running\n\nThe exporter needs to run as `root` in order to have enough permission to\nexecute the [`rctl_get_racct(2)`] calls.  If it is not run as `root`, it will\ncomplain and exit.\n\nAs jails may come and go during the lifetime of the exporter, so to will the\ntime series that the exporter exports.  If you wish to account for resource\nusage for jails that have disappeared, you may wish to make use of the\nPrometheus [recording rules] to track total resource usage across all jails.\n\nThe exporter can be run in two different ways. The default way is to run a\npersistent network daemon for Prometheus to scrape. The exporter will not\ndaemonize itself, instead, it is recommended to use a tool such as\n[`daemon(8)`].  See the included [`rc.d/jail_exporter.in`] for an example of\nthis.\n\nThe second way is to simply output the scraped metrics to a text file. This\nmode is designed to be paired with the [`node_exporter`] [Textfile Collector].\n\nNo port is available yet, but it should happen soon.\n\n## Exposed Metrics\n\nThis exporter was developed under FreeBSD 11.1 and currently exports all\nresources listed under the `RESOURCES` section of [`rctl(8)`].\n\nThe `id` and `num` time series are calculated based on other information and do\nnot come from [`rctl(8)`] directly. Metric names have their units appended\nwhere appropriate, based on the Prometheus best practice for [metric and label\nnaming].\n\nAll exported metrics are prefixed with `jail` and have a `name` label\nrepresenting the name of the jail. As such, jail names are expected to be\nunique.\n\nDescriptions of metrics are taken from the [`rctl(8)`] man page where\napplicable.\n\n### `rctl(8)` Metrics\n\nMetric                    | `rctl(8)` name    | Description\n--------------------------|-------------------|------------\n`coredumpsize_bytes`      | `coredumpsize`    | core dump size, in bytes\n`cputime_seconds_total`   | `cputime`         | CPU time, in seconds\n`datasize_bytes`          | `datasize`        | data size, in bytes\n`maxproc`                 | `maxproc`         | number of processes\n`memorylocked_bytes`      | `memorylocked`    | locked memory, in bytes\n`memoryuse_bytes`         | `memoryuse`       | resident set size, in bytes\n`msgqqueued`              | `msgqqueued`      | number of queued SysV messages\n`msgqsize_bytes`          | `msgqsize`        | SysV message queue size, in bytes\n`nmsgq`                   | `nmsgq`           | number of SysV message queues\n`nsem`                    | `nsem`            | number of SysV semaphores\n`nsemop`                  | `nsemop`          | number of SysV semaphores modified in a single semop(2) call\n`nshm`                    | `nshm`            | number of SysV shared memory segments\n`nthr`                    | `nthr`            | number of threads\n`openfiles`               | `openfiles`       | file descriptor table size\n`pcpu_used`               | `pcpu`            | %CPU, in percents of a single CPU core\n`pseudoterminals`         | `pseudoterminals` | number of PTYs\n`readbps`                 | `readbps`         | filesystem reads, in bytes per second\n`readiops`                | `readiops`        | filesystem reads, in operations per second\n`shmsize_bytes`           | `shmsize`         | SysV shared memory size, in bytes\n`stacksize_bytes`         | `stacksize`       | stack size, in bytes\n`swapuse_bytes`           | `swapuse`         | swap space that may be reserved or used, in bytes\n`vmemoryuse_bytes`        | `vmemoryuse`      | address space limit, in bytes\n`wallclock_seconds_total` | `wallclock`       | wallclock time, in seconds\n`writebps`                | `writebps`        | filesystem writes, in bytes per second\n`writeiops`               | `writeiops`       | filesystem writes, in operations per second\n\n### Non-`rctl(8)` Metrics\n\nMetric                | Description\n----------------------|------------\n`exporter_build_info` | The version of Rust used to build the exporter, and the version of the exporter.\n`id`                  | ID of the named jail\n`num`                 | Current number of running jails\n\n## Crate Features\n\nFeature      | Default | Description\n-------------|---------|------------\n`auth`       | `true`  | Enables HTTP Basic Authentication\n`bcrypt_cmd` | `true`  | Enables a `bcrypt` subcommand to assist with hashing passwords for HTTP Basic Authentication\n`rc_script`  | `true`  | Enables the `--rc-script` CLI flag to dump the [`rc(8)`] script to stdout\n\n## Notes\n\nThe `rc_script` feature is enabled by default for the benefit of users\ninstalling via `cargo install`. It is disabled by default in the FreeBSD port\nas the [`rc(8)`] script is supplied in the ports tree.\n\n[Build Status]: https://api.cirrus-ci.com/github/phyber/jail_exporter.svg\n[FreeBSD]: https://www.freebsd.org/\n[Prometheus]: https://prometheus.io/\n[RFC7617]: https://tools.ietf.org/html/rfc7617\n[Rust]: https://www.rust-lang.org/\n[Textfile Collector]: https://github.com/prometheus/node_exporter#textfile-collector\n[bcrypt]: https://en.wikipedia.org/wiki/Bcrypt\n[crates.io]: https://crates.io/crates/jail_exporter\n[jail]: https://crates.io/crates/jail\n[metric and label naming]: https://prometheus.io/docs/practices/naming/\n[rctl]: https://crates.io/crates/rctl\n[recording rules]: https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/\n[`daemon(8)`]: https://www.freebsd.org/cgi/man.cgi?query=daemon\u0026sektion=8\n[`exporter-toolkit`]: https://github.com/prometheus/exporter-toolkit\n[`make(1)`]: https://www.freebsd.org/cgi/man.cgi?query=make\u0026sektion=1\n[`node_exporter`]: https://github.com/prometheus/node_exporter\n[`rc(8)`]: https://man.freebsd.org/rc(8)\n[`rc.conf(5)`]: https://man.freebsd.org/rc.conf(5)\n[`rc.d/jail_exporter.in`]: rc.d/jail_exporter.in\n[`rctl(8)`]: https://www.freebsd.org/cgi/man.cgi?query=rctl\u0026sektion=8\n[`rctl_get_racct(2)`]: https://www.freebsd.org/cgi/man.cgi?query=rctl_get_racct\u0026sektion=2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphyber%2Fjail_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphyber%2Fjail_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphyber%2Fjail_exporter/lists"}