Netbox-ssot is a small but powerful microservice designed to keep your Netbox instance in sync with external data sources.
It is designed to be run as a cronjob, and will periodically update Netbox with the latest data from the external sources. It syncs each source in parallel to speed up the process of syncing.
Currently, the supported external data sources types are:
ovirtvmwarednacproxmoxpaloalto- PAN-OS firewall
fortigatefmcios-xe- All devices with ios-xe supporting netconf
Warning
This project is still under heavy development, use with caution.
-
v1.x.x works with
netbox>=4.0.0 -
v0.x.x works with
netbox>=3.7.0
Netbox-ssot is configured via a single yaml file. The configuration file is divided into three sections:
logger: Logger configurationnetbox: Netbox configurationsource: Array of configuration for each data source
Example configuration can be found here.
| Parameter | Description | Type | Possible values | Default | Required |
|---|---|---|---|---|---|
logger.level |
Log level | int | 0-3 | 1 | Yes |
logger.dest |
Log output filename. Default "" representing stdout. |
str | Any valid path | "" | No |
| Parameter | Description | Type | Possible values | Default | Required |
|---|---|---|---|---|---|
netbox.apiToken |
Netbox API token. | str | Any valid token | "" | Yes |
netbox.hostname |
Hostname of your netbox instance (e.g netbox.example.com). |
str | Valid hostname | "" | Yes |
netbox.port |
Port of your netbox instance. | int | 0-65536 | 443 | No |
netbox.httpScheme |
HTTP scheme of your netbox instance. | str | [http, https] | https | No |
netbox.validateCert |
Validate the TLS certificate of your netbox instance. | bool | [true, false] | false | No |
netbox.timeout |
Max timeout for api call of your netbox instance. | int | >=0 | 30 | No |
netbox.removeOrphans |
Automatically remove all objects tagged with netbox-ssot which, were not found on the sources, during this iteration. | bool | [true, false] | true | No |
netbox.tag |
Tag to be applied to all objects managed by netbox-ssot. | string | any | "netbox-ssot" | No |
netbox.tagColor |
TagColor for the netbox-ssot tag. | string | any | "07426b" | No |
netbox.sourcePriority |
Array of source names in order of priority. If an object (e.g. Vlan) is found in multiple sources, the first source in the list will be used. | []string | any | [] | No |
netbox.arpDataLifeSpan |
Lifespan of each arp data entry in seconds (if entry is not found in the following interations). | int | >0 | 172800 | No |
netbox.caFile |
Path to a self signed certificate for netbox. | string | Valid path | "" | No |
| Parameter | Description | Source Type | Type | Possible values | Default | Required |
|---|---|---|---|---|---|---|
source.name |
Name of the data source. | all | str | any | "" | Yes |
source.type |
Type of the data source. | all | str | [ovirt, vmware, dnac, proxmox, paloalto] | "" | Yes |
source.httpScheme |
Http scheme for the source | all | str | [ http,https] | https | No |
source.hostname |
Hostname of the data source. | all | str | any | "" | Yes |
source.port |
Port of the data source. | all | int | 0-65536 | 443 | No |
source.username |
Username of the data source account. | all | str | any | "" | Yes |
source.password |
Password of the data source account. | all | str | any | "" | Yes |
source.apiToken |
Password of the data source account. | [fortigate] | str | any | "" | Yes |
source.validateCert |
Enforce TLS certificate validation. | all | bool | [true, false] | false | No |
source.tagColor |
TagColor for the source tag. | all | string | any | Predefined | No |
source.ignoredSubnets |
List of subnets, which will be ignored (e.g. IPs won't be synced). | all | []string | any | [] | No |
source.interfaceFilter |
Regex representation of interface names to be ignored (e.g. (cali|vxlan|flannel|[a-f0-9]{15})) |
all | string | any | [] | No |
source.collectArpData |
Collect data from the arp table of the device. | [paloalto, ios-xe] | bool | [true, false] | false | No |
source.datacenterClusterGroupRelations |
Regex relations in format regex = clusterGroupName, that map each datacenter that satisfies regex to clusterGroupname (see #130). |
[vmware, ovirt] | []string | any | [] | No |
source.hostSiteRelations |
Regex relations in format regex = siteName, that map each host that satisfies regex to site. |
all | []string | any | [] | No |
source.clusterSiteRelations |
Regex relations in format regex = siteName, that map each cluster that satisfies regex to site. |
all | []string | any | [] | No |
source.clusterTenantRelations |
Regex relations in format regex = tenantName, that map each cluster that satisfies regex to tenant. |
all | []string | any | [] | No |
source.hostTenantRelations |
Regex relations in format regex = tenantName, that map each host that satisfies regex to tenant. |
all | []string | any | [] | No |
source.vmTenantRelations |
Regex relations in format regex = tenantName, that map each vm that satisfies regex to tenant. |
all | []string | any | [] | No |
source.vlanGroupRelations |
Regex relations in format regex = vlanGroup, that map each vlan that satisfies regex to vlanGroup. |
all | []string | any | [] | No |
source.vlanTenantRelations |
Regex relations in format regex = tenantName, that map each vlan that satisfies regex to tenant. |
all | []string | any | [] | No |
source.customFieldMappings |
Mappings of format customFieldName = option. Currently, supported options are contact, owner, description. |
[vmware] | []string | any | [] | No |
source.caFile |
Path to a self signed certificate for the source. | any | string | Valid path | "" | No |
logger:
level: 1
dest: ""
netbox:
apiToken: "el1aof2azu6n50ks5zcenp3..."
hostname: "netbox.example.com"
httpScheme: http
port: 443
timeout: 30
sourcePriority: ["olvm", "prodvmware", "prodprox", "dnacenter", "testvmware", "pa-uk", "fmc-lab"] # Not required, but recommended
source:
- name: olvm
type: ovirt
hostname: ovirt.example.com
port: 443
username: "admin"
password: "topsecret"
interfaceFilter: (cali|vxlan|flannel|docker|[a-f0-9]{15})
- name: prodvmware
type: vmware
hostname: vcenter.example.com
username: user
password: "top_secret"
clusterSiteRelations:
- .* = ExampleSite
hostSiteRelations:
- .*_NYC = New York
- nyc.* = New York
customFieldMappings: # Here we define map of our custom field names, to 3 option [email, owner, description]
- Mail = email
- Creator = owner
- Description = description
- name: prodprox
type: proxmox
username: svc@pve
password: changeme
hostname: 192.168.1.254
port: 8006
validateCert: false
clusterSiteRelations:
- .* = Site
- name: forti
type: fortigate
hostname: forti.example.com
apiToken: "apitokenhere"
validateCert: False
hostTenantRelations:
- .* = MyTenant
hostSiteRelations:
- .* = MyTenant
hostTenantRelations:
- .* = MyTenant
- name: pa-uk
type: paloalto
hostname: 192.168.1.52
username: user
password: passw0rd
hostTenantRelations:
- .* = MyTenant
hostSiteRelations:
- .* = MySite
vlanTenantRelations:
- .* = MyTenant
collectArpData: true
- name: dnacenter
type: dnac
hostname: dnac.example.com
username: user
password: "pa$$w0rd"
vlanTenantRelations:
- .* = MyTenant
- name: fmc-lab
type: fmc
hostname: 172.16.1.30
username: user
password: password
validateCert: False
hostTenantRelations:
- .* = MyTenant
hostSiteRelations:
- .* = MySite
vlanTenantRelations:
- .* = MyTenant
- name: cs1
type: ios-xe
hostname: 10.10.1.1
username: user
password: password
validateCert: False
hostTenantRelations:
- .* = MyTenant
hostSiteRelations:
- .* = MySite
vlanTenantRelations:
- .* = MyTenant
collectArpData:
true
docker run -v /path/to/config.yaml:/app/config.yaml ghcr.io/bl4ko/netbox-ssotCreate k8s secret from self defined config.yaml:
kubectl create secret generic netbox-ssot-secret --from-file=config.yamlApply cronjob with custom settings:
kubectl apply -f cronjob.yamlCreate self signed certificate e.g.:
kubectl create secret generic netbox-ssot-cert --from-file=sub.pem=./sub.pemUse cronjob with cert mounted:
kubectl apply -f cronjob_with_cert.yaml
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent