From 12d99f7978a6da2fbf8ab2b7cbe5df277c788f21 Mon Sep 17 00:00:00 2001 From: Seth Grover Date: Tue, 20 Sep 2022 13:12:21 -0600 Subject: [PATCH] readme --- Dockerfiles/netbox.Dockerfile | 14 ++++++++++++++ README.md | 3 ++- docker-compose-standalone.yml | 2 ++ docker-compose.yml | 2 ++ netbox/supervisord.conf | 12 ++++++++++++ 5 files changed, 32 insertions(+), 1 deletion(-) diff --git a/Dockerfiles/netbox.Dockerfile b/Dockerfiles/netbox.Dockerfile index 9d63b1437..932f23c2a 100644 --- a/Dockerfiles/netbox.Dockerfile +++ b/Dockerfiles/netbox.Dockerfile @@ -22,11 +22,19 @@ ENV PUSER "boxer" ENV PGROUP "boxer" ENV PUSER_PRIV_DROP true +ENV SUPERCRONIC_VERSION "0.2.1" +ENV SUPERCRONIC_URL "https://github.com/aptible/supercronic/releases/download/v$SUPERCRONIC_VERSION/supercronic-linux-amd64" +ENV SUPERCRONIC "supercronic-linux-amd64" +ENV SUPERCRONIC_SHA1SUM "d7f4c0886eb85249ad05ed592902fa6865bb9d70" +ENV SUPERCRONIC_CRONTAB "/etc/crontab" + ARG BASE_PATH=assets ARG NETBOX_DEFAULT_SITE=Malcolm +ARG NETBOX_CRON=false ENV BASE_PATH $BASE_PATH ENV NETBOX_DEFAULT_SITE $NETBOX_DEFAULT_SITE +ENV NETBOX_CRON $NETBOX_CRON RUN apt-get -q update && \ apt-get -y -q --no-install-recommends upgrade && \ @@ -38,6 +46,12 @@ RUN apt-get -q update && \ python3-slugify \ supervisor \ tini && \ + curl -fsSLO "$SUPERCRONIC_URL" && \ + echo "${SUPERCRONIC_SHA1SUM} ${SUPERCRONIC}" | sha1sum -c - && \ + chmod +x "$SUPERCRONIC" && \ + mv "$SUPERCRONIC" "/usr/local/bin/${SUPERCRONIC}" && \ + ln -s "/usr/local/bin/${SUPERCRONIC}" /usr/local/bin/supercronic && \ + touch "${SUPERCRONIC_CRONTAB}" && \ apt-get -q -y autoremove && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \ diff --git a/README.md b/README.md index f8d7be4f4..b111cd7a2 100644 --- a/README.md +++ b/README.md @@ -580,6 +580,7 @@ Various other environment variables inside of `docker-compose.yml` can be tweake * `OPENSEARCH_SECONDARY_URL` - when forwarding to a secondary remote OpenSearch instance (i.e., `OPENSEARCH_SECONDARY` is `true`) this value specifies the secondary remote instance URL in the format `protocol://host:port` * `OPENSEARCH_SECONDARY_SSL_CERTIFICATE_VERIFICATION` - if set to `true`, connections to the secondary remote OpenSearch instance will require full TLS certificate validation (this may fail if using self-signed certificates) (default `false`) * `NETBOX_DISABLED` - if set to `true`, Malcolm will **not** start [NetBox](#NetBox) and manage a [NetBox](#NetBox) instance (default `true`) +* `NETBOX_CRON` - if set to `true`, network traffic metadata will periodically be queried and used to populate Malcolm's [NetBox](#NetBox) instance * `NGINX_BASIC_AUTH` - if set to `true`, use [TLS-encrypted HTTP basic](#AuthBasicAccountManagement) authentication (default); if set to `false`, use [Lightweight Directory Access Protocol (LDAP)](#AuthLDAP) authentication * `NGINX_LOG_ACCESS_AND_ERRORS` - if set to `true`, all access to Malcolm via its [web interfaces](#UserInterfaceURLs) will be logged to OpenSearch (default `false`) * `NGINX_SSL` - if set to `true`, require HTTPS connections to Malcolm's `nginx-proxy` container (default); if set to `false`, use unencrypted HTTP connections (using unsecured HTTP connections is **NOT** recommended unless you are running Malcolm behind another reverse proxy like Traefik, Caddy, etc.) @@ -1707,7 +1708,7 @@ This feature is disabled by default, but it can be enabled by clearing (setting Malcolm provides an instance of [NetBox](https://netbox.dev/), an open-source "solution for modeling and documenting modern networks." The NetBox web interface is available at at [https://localhost/assets/](https://localhost/assets/) if you are connecting locally. -Deeper integration between Malcolm and Netbox is a work in progress, with the eventual goal being for Malcolm to automatically create objects in NetBox based on traffic observed and/or enrich its own network traffic metadata based on NetBox inventory. +The design of a potentially deeper integration between Malcolm and Netbox is a work in progress. The purpose of an asset management system is to document the intended state of a network: were Malcolm to actively and agressively populate NetBox with the live network state, a network configuration fault could result in an incorrect documented configuration. The Malcolm development team is investigating what data, if any, should automatically flow to NetBox based on traffic observed (enabled via the `NETBOX_CRON` [environment variable in `docker-compose.yml`](#DockerComposeYml)), and what NetBox inventory data could be used, if any, to enrich Malcolm's network traffic metadata. Please see the [NetBox page on GitHub](https://github.com/netbox-community/netbox), its [documentation](https://docs.netbox.dev/en/stable/) and its [public demo](https://demo.netbox.dev/) for more information. diff --git a/docker-compose-standalone.yml b/docker-compose-standalone.yml index 440c71d49..cd1ceb724 100644 --- a/docker-compose-standalone.yml +++ b/docker-compose-standalone.yml @@ -272,6 +272,8 @@ x-netbox-variables: &netbox-variables NETBOX_POSTGRES_DISABLED : *netboxdisabled NETBOX_REDIS_DISABLED : *netboxdisabled NETBOX_REDIS_CACHE_DISABLED : *netboxdisabled + # Whether or not to periodically query network traffic metadata and use it to populate NetBox + NETBOX_CRON : 'false' # If using the NetBox interface to create API tokens, set this # (see https://docs.djangoproject.com/en/4.1/ref/settings/#csrf-trusted-origins) # CSRF_TRUSTED_ORIGINS : 'https://malcolm.example.org' diff --git a/docker-compose.yml b/docker-compose.yml index cb98ce71c..192fa4b61 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -272,6 +272,8 @@ x-netbox-variables: &netbox-variables NETBOX_POSTGRES_DISABLED : *netboxdisabled NETBOX_REDIS_DISABLED : *netboxdisabled NETBOX_REDIS_CACHE_DISABLED : *netboxdisabled + # Whether or not to periodically query network traffic metadata and use it to populate NetBox + NETBOX_CRON : 'false' # If using the NetBox interface to create API tokens, set this # (see https://docs.djangoproject.com/en/4.1/ref/settings/#csrf-trusted-origins) # CSRF_TRUSTED_ORIGINS : 'https://malcolm.example.org' diff --git a/netbox/supervisord.conf b/netbox/supervisord.conf index 081c47744..4f2f0d451 100644 --- a/netbox/supervisord.conf +++ b/netbox/supervisord.conf @@ -1,3 +1,5 @@ +; Copyright (c) 2022 Battelle Energy Alliance, LLC. All rights reserved. + [unix_http_server] file=/dev/shm/supervisor.sock chmod=0700 @@ -74,3 +76,13 @@ stdout_logfile=/dev/fd/1 stdout_logfile_maxbytes=0 stdout_logfile_backups=0 redirect_stderr=true + +[program:cron] +command=/usr/local/bin/supercronic -json "%(ENV_SUPERCRONIC_CRONTAB)s" +autostart=%(ENV_NETBOX_CRON)s +autorestart=true +stopasgroup=true +killasgroup=true +stdout_logfile=/dev/fd/1 +stdout_logfile_maxbytes=0 +redirect_stderr=true