Skip to content

Usage

Jump to bottom
Nicholas St. Germain edited this page Jan 22, 2019 · 37 revisions

Command line arguments can be viewed by running:

docker run --rm pyouroboros/ouroboros --help

Options

All command line arguments can be substituted with an environment variable. command line options are kebab-case and environment variables are SCREAMING_CASE. E.g. --docker-sockets vs. DOCKER_SOCKETS. All examples will be given as environment variables for a docker run as --help will show command line examples

Help

Type: Boolean - Interrupting
Command Line: -h, --help

Shows the help message then exits

Core

Version

Type: Boolean - Interrupting
Command Line: -v, --version

Shows the current version number then exits

Docker Sockets

Type: List - Space separated
Command Line: -d, --docker-sockets
Environment Variable: DOCKER_SOCKETS
Default: unix://var/run/docker.sock
Example: -e DOCKER_SOCKETS="unix://var/run/docker.sock tcp://192.168.1.100:2376"

Allows you to define a list of docker sockets. If defined, it does not include the local socket by default.

Docker TLS Verify

Type: Boolean
Command Line: -t, --docker-tls-verify
Environment Variable: DOCKER_TLS_VERIFY
Default: False
Example: -e DOCKER_TLS_VERIFY=true -v $DOCKER_CERT_FOLDER:/root/.docker/

Enables docker TLS secure client connections by certificate

Interval

Type: Integer
Command Line: -i, --interval
Environment Variable: INTERVAL
Example: -e INTERVAL=300

The interval in seconds between checking for updates. There is a hard-coded 30 second minimum. Anything lower than that will set to 30.

Log Level

Type: String - Choice
Command Line: -l, --log-level
Environment Variable: LOG_LEVEL
Choices:

  • debug
  • info
  • warn
  • error
  • critical

Example: -e LOG_LEVEL=info

Sets your logging verbosity level.

Self Update

Type: Boolean
Command Line: -u, --self-update
Environment Variable: SELF_UPDATE
Default: False
Example: -e SELF_UPDATE=true

Let ouroboros update itself in addition to your other containers. Self updates require the the container to be named either ouroboros or ouroboros-updated and will alternate the former names for updates. Self updates will wipe update counters for notifications.

Run Once

Type: Boolean - Interrupting
Command Line: -o, --run-once
Default: False

Ouroboros will only do a single pass of all container checks, and then exit. This is a great way to granularly control scheduling with an outside scheduler like cron. If during the single pass ouroboros has to self-update, it will do another full pass after updating itself to ensure that all containers were checked.

Docker Specifics

Monitor

Type: List - Space separated
Command Line: -m, --monitor
Environment Variable: MONITOR
Default: All
Example: -e MONITOR="nginx telegraf portainer"

Define a list of containers you would like to monitor instead of all containers. If defined, labels then ignore take precedence. If a container is listed that does not match the name of currently running containers, it will be ignored.

Ignore

Type: List - Space separated
Command Line: -n, --ignore
Environment Variable: IGNORE
Default: None
Example: -e IGNORE="mariadb influxdb mongo postgres"

Define a list of containers you would like to ignore updates for. If a container is listed that does not match the name of currently running containers, it will be ignored.

Label Enable

Type: Boolean
Command Line: -k, --label-enable
Environment Variable: LABEL_ENABLE
Default: False
Example: -e LABEL_ENABLE=true

If a container has a com.ouroboros.enable label, only watch it if it is set to true. Supersedes monitor/ignore in precedence. This can be achieved by setting LABEL com.ouroboros.enable="false" in your Dockerfile or passing the label during creation of the container with docker run -d --label=com.ouroboros.enable="false" person/image:tag

Cleanup

Type: Boolean
Command Line: -c, --cleanup
Environment Variable: CLEANUP
Default: False
Example: -e CLEANUP=true

Remove the old images after updating. If you have multiple containers using the same image, it will ensure all containers are updated before successfully removing the image.

Latest

Type: Boolean
Command Line: -L, --latest
Environment Variable: LATEST
Default: False
Example: -e LATEST=true

Pull the :latest tags and update all containers to it, regardless of the current tag the container is running as.

Repository User

Type: String
Command Line: -r, --repo-user
Environment Variable: REPO_USER
Default: None
Example: -e REPO_USER=johndoe1970

Define a username for repository authentication. Will be ignored without defining a repository password.

Repository Password

Type: String
Command Line: -R, --repo-pass
Environment Variable: REPO_PASS
Default: None
Example: -e REPO_PASS=0791eodnhoj

Define a password for repository authentication. Will be ignored without defining a repository username.

Docker: Configuration of docker functionality

-m MONITOR [MONITOR ...], --monitor MONITOR [MONITOR ...] Which container(s) to monitor DEFAULT: All -n IGNORE [IGNORE ...], --ignore IGNORE [IGNORE ...] Container(s) to ignore EXAMPLE: -n container1 container2 -c, --cleanup Remove old images after updating -L, --latest Check for latest image instead of pulling current tag -r REPO_USER, --repo-user REPO_USER Private docker registry username EXAMPLE: [email protected] -R REPO_PASS, --repo-pass REPO_PASS Private docker registry password EXAMPLE: MyPa$$w0rd

Data Export: Configuration of data export functionality

-D {prometheus,influxdb}, --data-export {prometheus,influxdb} Enable exporting of data for chosen option -a PROMETHEUS_ADDR, --prometheus-addr PROMETHEUS_ADDR Bind address to run Prometheus exporter on. Has no effect without --data-export prometheus DEFAULT: 127.0.0.1 -p PROMETHEUS_PORT, --prometheus-port PROMETHEUS_PORT Port to run Prometheus exporter on. Has no effect without --data-export prometheus DEFAULT: 8000 -I INFLUX_URL, --influx-url INFLUX_URL URL for influxdb, Has no effect without --data-export influxdb DEFAULT: 127.0.0.1 -P INFLUX_PORT, --influx-port INFLUX_PORT PORT for influxdb, Has no effect without --data-export influxdb DEFAULT: 8086 -U INFLUX_USERNAME, --influx-username INFLUX_USERNAME Username for influxdb, Has no effect without --data-export influxdb DEFAULT: root -x INFLUX_PASSWORD, --influx-password INFLUX_PASSWORD Password for influxdb, Has no effect without --data-export influxdb DEFAULT: root -X INFLUX_DATABASE, --influx-database INFLUX_DATABASE Database for influxdb, Required if using influxdb. Has no effect without --data-export influxdb. DEFAULT: root -s, --influx-ssl Use SSL when connecting to influxdb -V, --influx-verify-ssl Verify SSL certificate when connecting to influxdb

Notifications: Configuration of notification functionality

-w WEBHOOK_URLS [WEBHOOK_URLS ...], --webhook-urls WEBHOOK_URLS [WEBHOOK_URLS ...] Webhook POST urls EXAMPLE: -w https://domain.tld/1234/asdf http://123.123.123.123:4040/re235 -y PUSHOVER_TOKEN, --pushover-token PUSHOVER_TOKEN Pushover token to authenticate against application EXAMPLE: -y af2r52352asd -Y PUSHOVER_DEVICE, --pushover-device PUSHOVER_DEVICE Device to receive pushover notification EXAMPLE: -Y SamsungGalaxyS8 -z PUSHOVER_USER, --pushover-user PUSHOVER_USER Pushover user bound to application EXAMPLE: -z asdfweawefasdfawef -e SMTP_HOST, --smtp-host SMTP_HOST SMTP relay hostname EXAMPLE: -e smtp.gmail.com -E SMTP_PORT, --smtp-port SMTP_PORT SMTP relay port EXAMPLE: -E 587 -f, --smtp-starttls SMTP relay uses STARTTLS -F SMTP_USERNAME, --smtp-username SMTP_USERNAME SMTP relay username EXAMPLE: -F [email protected] -g SMTP_PASSWORD, --smtp-password SMTP_PASSWORD SMTP relay password EXAMPLE: -g MyPa$$w0rd -G SMTP_RECIPIENTS [SMTP_RECIPIENTS ...], --smtp-recipients SMTP_RECIPIENTS [SMTP_RECIPIENTS ...] SMTP notification recipients EXAMPLE: -G [email protected] [email protected] -j SMTP_FROM_EMAIL, --smtp-from-email SMTP_FROM_EMAIL SMTP from email EXAMPLE: -g [email protected] -J SMTP_FROM_NAME, --smtp-from-name SMTP_FROM_NAME SMTP from name DEFAULT: Ouroboros

EXAMPLE: ouroboros -d tcp://1.2.3.4:5678 -i 20 -m container1 container2 -l warn


## Config File

You can provide a docker env file to supplement a config file with all the above listed arguments by utilizing the supported environment variables.

```bash
docker run -d --name ouroboros \
  --env-file env.list \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros

Sample env.list:

DOCKER_SOCKETS=tcp://localhost:2375
INTERVAL=60
MONITOR="container_1 container_2"

Docker Compose

version: '3'
services:
  nginx:
    image: nginx:1.14-alpine
    ports:
     - 80:80
  ouroboros:
    image: pyouroboros/ouroboros
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 60 --log-level debug
    environment:
    - REPO_USER=user
    - REPO_PASS=password

Examples

Change update frequency

An interval argument can be supplied to change how often ouroboros checks the remote docker registry for image updates (in seconds).

Default is 300s

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --interval 600

Monitor select containers

By default, ouroboros will monitor all running docker containers, but can be overridden to only monitor select containers by passing a monitor argument which supports an infinite amount of container names.

Default is all

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --monitor container_1 container_2 container_3

Ignore select containers

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --ignore container_1 container_2 container_3

Change loglevel

The amount of logging details can be suppressed by providing a log-level argument.

Default is info

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --log-level debug

Update all containers and quit ouroboros

If you prefer ouroboros didn't run all the time and only update all of your running containers in one go, provide the run-once argument and ouroboros will terminate itself after updating all your containers one time.

Default is False

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --run-once

Remove old docker images

Ouroboros has the option to remove the older docker image if a new one is found and the container is then updated. To tidy up after updates, pass the cleanup argument.

Default is False

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --cleanup

Prometheus metrics

Ouroboros keeps track of containers being updated and how many are being monitored. Said metrics are exported using prometheus. You can also bind the http server to a different interface for systems using multiple networks. --prometheus-port and --prometheus-addr can run independently of each other without issue.

Prometheus exporter will not be reachable by default inside of a container. You will need to intentionally bind to 0.0.0.0 for docker network interfaces to be able to reach the exporter the host network. This was done intentionally for security reasons.

Bind Address & Port

Bind Address default is 127.0.0.1

Port Default is 8000

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 pyouroboros/ouroboros --data-export prometheus --prometheus-addr 0.0.0.0

You should then be able to see the metrics at http://localhost:8000/

Example text from endpoint:

# HELP containers_updated_total Count of containers updated
# TYPE containers_updated_total counter
containers_updated_total{container="all"} 2.0
containers_updated_total{container="alpine"} 1.0
containers_updated_total{container="busybox"} 1.0
# TYPE containers_updated_created gauge
containers_updated_created{container="all"} 1542152615.625264
containers_updated_created{container="alpine"} 1542152615.6252713
containers_updated_created{container="busybox"} 1542152627.7476819
# HELP containers_being_monitored Count of containers being monitored
# TYPE containers_being_monitored gauge
containers_being_monitored 2.0

Webhook Notifications

See the notifications wiki for more details.

Default is None

docker run -d --name ouroboros \
 -v /var/run/docker.sock:/var/run/docker.sock \
 pyouroboros/ouroboros --webhook-urls https://hooks.slack.com/something https://discordapp.com/api/webhooks/something
Clone this wiki locally