lae.netbox

以下是文本的中文翻译：

:role-author: lae :role-name: netbox :role: {role-author}.{role-name} :gh-name: {role-author}/ansible-role-{role-name} :netbox-version: 3.7.3

= {role} :toc: :toc-placement: preamble ifdef::env-github[] :tip-caption: :bulb: :warning-caption: :warning: endif::[]

ifdef::env-github[] image:https://img.shields.io/badge/role-{role}-blue?style=for-the-badge[Ansible Galaxy 角色, link=https://galaxy.ansible.com/{role-author}/{role-name}] endif::env-github[]

部署和配置 https://github.com/netbox-community/netbox[NetBox]，一个IP地址管理（IPAM）和数据中心基础设施管理（DCIM）工具。

此角色将通过发布的tar包或使用git在其自己的虚拟环境中部署NetBox，并使用uWSGI作为应用服务器。

支持CentOS 7,8 / RHEL 9 / Debian 9,10,11,12 / Ubuntu 16, 18, 20和22。

请注意，此角色的安装方式与NetBox文档中的安装说明略有不同。主要差异为：

使用发行版提供的systemd而不是supervisord
使用uWSGI作为应用服务器而不是gunicorn
加固NetBox/uWSGI服务（请参见templates/netbox.service.j2）
升级和配置更改时将热重载

== 快速开始

假设您已安装Ansible并使用默认设置：

[source,bash,subs="attributes"]

ansible-galaxy install geerlingguy.postgresql davidwittman.redis {role} ansible-galaxy collection install community.postgresql ansible-playbook -i your.server.fqdn, ~/.ansible/roles/{role}/examples/playbook_single_host_deploy.yml -K

这将部署NetBox和PostgreSQL在your.server.fqdn上；完成后应可以通过80端口访问。如果需要，请进行修改。有关更多信息请阅读下方内容。

如果您喜欢，也可以使用Vagrant在localhost:8080上启动NetBox：

[source,bash,subs="attributes"]

ansible-galaxy install geerlingguy.postgresql davidwittman.redis {role} ansible-galaxy collection install community.postgresql cd ~/.ansible/roles/{role}/ vagrant up

== 支持/贡献

如果您想为此角色做贡献，请阅读本存储库的工作流程和（可选）设置开发环境的说明，见DEVELOPING.md。此角色在Travis CI下测试时使用lae.travis-lxc角色，相关定义可以在tests/目录中找到。

ifeval::["{role-author}" == "lae"] 如有支持需求或想要贡献此角色但需要指导，请在@lae的Discord服务器中提问：https://discord.gg/cjqr6Fg endif::[]

== 先决条件

=== PostgreSQL

此角色不会设置PostgreSQL服务器（但如果需要将创建数据库），因此您需要自己设置PostgreSQL服务器并创建一个独立于此角色的数据库用户。请查看_示例剧本_部分。

此外，针对Ansible 2.10+，您可能需要安装community.postgresql集合。建议在您的剧本的requirements.yml文件中指定这一点。例如：

[source,yaml]

collections:

name: community.postgresql version: 3.4.0

警告：NetBox v2.2.0+需至少的PostgreSQL 9.4，这可能在您的发行版的库中不可用。您可能想用一个角色来处理这个问题。

=== Redis

此角色不设置或管理Redis实例。您可以选择在剧本中的pre_tasks任务中通过任务安装redis-server，或使用诸如https://galaxy.ansible.com/davidwittman/redis[DavidWittman.redis]的Redis安装角色。

警告：NetBox v2.9.0+至少需要Redis 4.0。上述建议的角色默认使用2.8版本，确保您在角色变量中指定较新版本，或以其他方式部署Redis 4.0+。

== 角色变量

提示：查看examples/中您可以为不同场景编写的一些剧本。

警告：有几个角色变量是必需的。请注意下面的粗体必需。

[source,yaml]

netbox_stable: false netbox_git: false

必须将上面其中一个变量设置为true。netbox_stable告诉角色通过从GitHub提取tar包发布来部署，而netbox_git则告诉角色克隆NetBox的git仓库——这两个选项是互斥的。

[source,yaml,subs="attributes"]

netbox_stable_version: {netbox-version} netbox_stable_uri: "https://github.com/netbox-community/netbox/archive/v{{ netbox_stable_version }}.tar.gz"

可以配置这些以固定版本（例如，递增以触发升级）或使用位于其他地方的tar包进行部署。在您需要修改某个发布内容或在防火墙后部署本地时很有用。

[source,yaml]

netbox_git_version: develop netbox_git_uri: "https://github.com/netbox-community/netbox.git"

netbox_git_version可以是git仓库中的任何有效引用。 netbox_git_uri可以指向例如本地仓库或分支。

[source,yaml]

netbox_superuser_enabled: true netbox_superuser_username: admin #netbox_superuser_password: changeme netbox_superuser_email: admin@localhost netbox_superuser_create_token: false

这些变量用于配置本地超级用户账户。如果您不想创建一个（例如在使用LDAP时），请禁用此项——尽管在这种情况下拥有本地超级用户仍然有益。启用时，必须设置超级用户密码。如果用户不存在，将创建新的超级用户；如果用户存在但不是超级用户或拥有不同的电子邮件或密码，则会修改现有用户。（是的，您可以用此来重置超级用户密码）。netbox_superuser_create_token可用于在需要时为超级用户生成随机API令牌。

[source,yaml]

netbox_database: netbox netbox_database_user: netbox #netbox_database_password: changeme #netbox_database_host: localhost netbox_database_port: 5432 #netbox_database_socket: /var/run/postgresql

必须配置UNIX套接字目录（以通过UNIX套接字通信）或主机/密码（以使用TCP/IP）。有关配置数据库的更多信息，请参见_示例剧本_部分。

请注意，这些用于在configuration.py中配置DATABASE。

[source,yaml]

netbox_database_conn_age: 300

要配置Netbox以保持数据库连接开放超过单个请求，请将netbox_database_conn_age设置为您首选的最大连接年龄（以秒为单位）。 300秒（5分钟）通常是一个不错的开始。

[source,yaml]

netbox_database_maintenance: postgres

如果postgres数据库配置为仅允许对Netbox配置的用户访问数据库的特定表，您可以将netbox_database_maintenance设置为替换用于连接检查的默认数据库，使用不同于默认postgres的表。默认情况下，这是每个postgres数据库中的一个空表，但某些配置可能会阻止对该表的访问，因此此处可以使用其他表（例如netbox_prod）。

[source,yaml]

示例用法，默认是空字典

netbox_database_options: sslmode: require isolation_level: 3

如果您需要设置任何其他PostgreSQL参数关键词，可以在这里进行设置。对于诸如 https://docs.djangoproject.com/en/3.1/ref/databases/#isolation-level[隔离级别] 的情况，必须使用数值而不是常量： psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE vs 3。只有在您确实知道自己在做什么的情况下，才在此添加内容。

[source,yaml]

netbox_redis_host: 127.0.0.1 netbox_redis_port: 6379 netbox_redis_password: '' netbox_redis_database: 0 netbox_redis_default_timeout: 300 netbox_redis_ssl_enabled: false netbox_redis_insecure_skip_tls_verify: false

netbox_redis_cache_host: "{{ netbox_redis_host }}" netbox_redis_cache_port: "{{ netbox_redis_port }}" netbox_redis_cache_database: 1 netbox_redis_cache_password: "{{ netbox_redis_password }}" netbox_redis_cache_default_timeout: "{{ netbox_redis_default_timeout }}" netbox_redis_cache_ssl_enabled: "{{ netbox_redis_ssl_enabled }}" netbox_redis_cache_insecure_skip_tls_verify: "{{ netbox_redis_insecure_skip_tls_verify }}"

这会填充configuration.py中的REDIS配置字典。如果您希望将缓存数据库与webhook数据库分开使用第二组变量。

[source,yaml]

netbox_redis_sentinels:

{ host: '192.168.0.1', port: '5000' },
{ host: '192.168.0.2', port: '5000' } netbox_redis_sentinel_service: 'netbox' netbox_redis_password: '' netbox_redis_database: 0 netbox_redis_default_timeout: 300 netbox_redis_ssl_enabled: false

netbox_redis_cache_sentinels: "{{ netbox_redis_sentinels }}" netbox_redis_cache_sentinel_service: "{{ netbox_redis_sentinel_service }}" netbox_redis_cache_database: 1 netbox_redis_cache_password: "{{ netbox_redis_password }}" netbox_redis_cache_default_timeout: "{{ netbox_redis_default_timeout }}" netbox_redis_cache_ssl_enabled: "{{ netbox_redis_ssl_enabled }}"

如果您的Redis是以哨兵架构（多个节点）安装的，则使用此语法。如果希望将缓存数据库与webhook数据库分开，使用第二组变量。

[source,yaml]

netbox_rqworker_processes: 1

指定系统d服务应启动多少个请求队列worker。您可以将此保持在默认的1，除非您有大量报告、脚本和其他后台任务。

[source,yaml]

netbox_config: #SECRET_KEY: ALLOWED_HOSTS: - localhost - 127.0.0.1 #NAPALM_USERNAME: #NAPALM_PASSWORD: MEDIA_ROOT: "{{ netbox_shared_path }}/media" REPORTS_ROOT: "{{ netbox_shared_path }}/reports" SCRIPTS_ROOT: "{{ netbox_shared_path }}/scripts"

这是用于模板化NetBox的configuration.py的设置字典。请查看http://netbox.readthedocs.io/en/stable/configuration/mandatory-settings/[必需设置]和http://netbox.readthedocs.io/en/stable/configuration/optional-settings/[可选设置]以获取更多详细信息，以及本存储库中的`examples/netbox_config.yml`。

在这里定义SECRET_KEY不是必需的——此角色将自动为您在{{ netbox_shared_path }}/generated_secret_key生成一个。随后，将会在运行过程中从该文件中读取SECRET_KEY，除非您稍后在剧本中对此进行设置。如果您在一个负载均衡器后部署多个NetBox实例，则应定义SECRET_KEY。

如果您在此角色中启用了NAPALM集成，您还需要在此配置NAPALM凭据。

MEDIA_ROOT/REPORTS_ROOT/SCRIPTS_ROOT，虽然在NetBox文档中不是强制的，但在此角色中是强制的，以防止在升级过程中丢失这些文件（此角色不进行原地升级NetBox）。它应设置为不会在升级过程中丢失的永久目录（上述默认值可以使用）。此角色将尝试创建这些目录并更改其所有权为netbox_user设置的值。

[source,yaml]

netbox_scripts: [] netbox_reports: []

https://netbox.readthedocs.io/en/stable/additional-features/custom-scripts/[脚本]和https://netbox.readthedocs.io/en/stable/additional-features/reports/[报告]的上传，以便在NetBox中使用。这些应该是有`src`属性的字典列表，指定脚本或报告的本地路径，以及`name`属性，指定模块名称（脚本/报告名称）。例如：

[source,yaml]

示例

netbox_scripts:

src: netbox_scripts/migrate_application.py name: migrate_application netbox_reports:
src: netbox_reports/devices.py name: devices

这将把netbox_scripts/migrate_application.py从您的剧本目录复制到{{ netbox_config.SCRIPTS_ROOT }}/migrate_application.py，并将netbox_reports/devices.py复制到{{ netbox.config.REPORTS_ROOT }}/devices.py。

[source,yaml]

netbox_pip_packages: []

示例：

netbox_pip_packages:

https://github.com/steffann/netbox-example-plugin.git
netbox-topology-views

这是要在NetBox的虚拟环境内通过pip安装的额外包列表。您可以指定任何有效的pip可以理解的制品。

如果在此列出任何插件，请确保在netbox_config角色变量中包含适当的插件配置。请查阅https://netbox.readthedocs.io/en/stable/plugins/[插件]以获取更多信息。

[source,yaml]

netbox_user: netbox netbox_group: netbox netbox_home: /srv/netbox netbox_releases_path: "{{ netbox_home }}/releases" netbox_git_repo_path: "{{ netbox_releases_path }}/git-repo" netbox_git_deploy_path: "{{ netbox_releases_path }}/git-deploy" netbox_stable_path: "{{ netbox_releases_path }}/netbox-{{ netbox_stable_version }}" netbox_current_path: "{{ netbox_home }}/current" netbox_shared_path: "{{ netbox_home }}/shared"

这些都是您可以修改的部署细节，以便更改应用程序用户和应用程序存储位置。netbox_releases_path存储了您曾部署过的所有NetBox版本。netbox_git_repo_path是克隆Git仓库的位置，应保持不变——而netbox_git_deploy_path是使用引用netbox_git_version提取的git archive文件的位置。netbox_stable_path是从发布tar包中提取的文件夹。netbox_current_path将链接到所选版本并在服务/配置文件中用作安装NetBox的位置。netbox_shared_path用于存储配置文件和其他“共享”内容，如日志文件。

[source,yaml]

netbox_socket: "127.0.0.1:8000" netbox_protocol: http netbox_processes: "{{ ansible_processor_vcpus }}"

netbox_socket定义了uWSGI服务将绑定到的地址，可以设置为任何有效的https://www.freedesktop.org/software/systemd/man/systemd.socket.html#ListenStream=[ListenStream]地址（systemd socket）。如果您希望uWSGI使用WSGI交流，请将netbox_protocol设置为uwsgi（例如，如果您在使用nginx作为负载均衡器时）。 netbox_processes定义了uWSGI将启动多少个NetBox工作进程以处理请求。

[source,yaml]

netbox_application_log: "file:{{ netbox_shared_path }}/application.log" netbox_requests_log: "file:{{ netbox_shared_path }}/requests.log"

这些定义了日志将存储的位置。如果您愿意，可以使用外部日志设施而不是本地文件， http://uwsgi-docs.readthedocs.io/en/latest/Logging.html#pluggable-loggers[只要uWSGI支持即可]。应用程序日志与`logger`相关，而请求日志与`req-logger`相关。

[source,yaml]

netbox_ldap_enabled: false netbox_ldap_config_template: netbox_ldap_config.py.j2

将netbox_ldap_enabled切换为true以配置NetBox的LDAP身份验证。netbox_ldap_config_template应是您的模板路径——默认情况下，Ansible会在剧本的templates/目录中查找此项。您可以在examples/中找到示例。您还需要将netbox_config.REMOTE_AUTH_BACKEND设置为netbox.authentication.LDAPBackend。

提示：默认情况下，根据该角色仍将创建本地（非LDAP）超级用户。如果这不符合您的期望，请考虑切换netbox_superuser_enabled。

[source,yaml]

netbox_napalm_enabled: false netbox_napalm_packages:

napalm

将netbox_napalm_enabled切换为true以启用NetBox中的NAPALM集成。您必须在netbox_config变量中定义NAPALM_USERNAME和NAPALM_PASSWORD才能使用NAPALM。在netbox_napalm_packages中列出额外的NAPALM Python库（例如napalm-eos）。

[source,yaml] netbox_metrics_enabled: false

将netbox_metrics_enabled切换为true以启用应用程序度量（通过 https://github.com/korfuri/django-prometheus[django-prometheus]）。这将添加相关的配置片段以进行适当的度量处理。 (https://netbox.readthedocs.io/en/stable/additional-features/prometheus-metrics/[更多信息]）。

[source,yaml]

netbox_metrics_dir: netbox_metrics netbox_metrics_path: "/run/{{ netbox_metrics_dir }}"

可以使用netbox_metrics_dir设置存储度量文件的目录名称。然而，netbox_metrics_path必须保持为默认值（见上文），以与systemd和RuntimeDirectory参数（只指向/run）共同工作。

[source,yaml] netbox_keep_uwsgi_updated: false

如果您希望确保您的uwsgi服务器是最新版本，请将netbox_keep_uwsgi_updated切换为true，否则在您后续运行剧本时uWSGI将不会被更新。

[source,yaml] netbox_uwsgi_options: {}

在此处指定要插入到uwsgi.ini中的额外配置选项。这应该是一个键/值对字典，例如buffer-size: 65535。

[source,yaml] netbox_uwsgi_in_venv: false

如果您希望uwsgi在与NetBox相同的虚拟环境中安装，则将netbox_uwsgi_in_venv切换为true。否则，它将安装在创建虚拟环境所用的python版本的库路径中（正常/传统行为）。

警告：在此角色的后续版本中可能会将此行为改为默认值（在经过更广泛的跨平台测试后）。有关更多详细信息，请查看https://github.com/lae/ansible-role-netbox/issues/144[问题#144]。

[source,yaml] netbox_install_epel: true

如果您不希望此角色为您安装Fedora EPEL，请将netbox_install_epel切换为false。这对于企业环境中管理/镜像系统仓库很有用。

[source,yaml]

netbox_packages: [] netbox_python_packages: [] netbox_python_binary: /usr/bin/python{{ some version }} netbox_ldap_packages: []

这些变量是根据目标发行版动态生成的。您可以在vars/目录下检查这些默认值。您可以使用这些变量来针对不受支持的操作系统（尽管欢迎您提交PR以添加支持！）或指定用于部署的自定义Python解释器（如PyPy）。尽管如此，请注意此角色对替代Python安装的支持可能有限。

== 示例剧本

以下使用@geerlingguy的强大Postgres角色安装PostgreSQL并创建用户，然后继续使用本地unix套接字进行部署和配置NetBox与默认的netbox数据库用户。

[source,yaml,subs="attributes"]

hosts: netbox.idolactiviti.es become: yes roles:
- geerlingguy.postgresql
- davidwittman.redis
- {role} vars: netbox_stable: true netbox_database_socket: "{{ postgresql_unix_socket_directories[0] }}" netbox_superuser_password: netbox netbox_socket: "0.0.0.0:80" netbox_config: ALLOWED_HOSTS:
  - netbox.idolactiviti.es MEDIA_ROOT: "{{ netbox_shared_path }}/media" REPORTS_ROOT: "{{ netbox_shared_path }}/reports" SCRIPTS_ROOT: "{{ netbox_shared_path }}/scripts" postgresql_users:
  - name: "{{ netbox_database_user }}" role_attr_flags: CREATEDB,NOSUPERUSER redis_bind: 127.0.0.1 redis_version: 6.0.9 redis_checksum: sha256:dc2bdcf81c620e9f09cfd12e85d3bc631c897b2db7a55218fd8a65eaa37f86dd

请注意CREATEDB属性。

假设您已有运行中的PG服务器，且用户netbox_prod_user已被创建，拥有一个名为netbox_prod的数据库，并允许您要在其上安装NetBox的主机通过TCP进行身份验证：

[source,yaml,subs="attributes"]

hosts: netbox.idolactiviti.es become: yes roles:
- davidwittman.redis
- {role} vars: netbox_stable: true netbox_superuser_password: netbox netbox_socket: "0.0.0.0:80" netbox_config: ALLOWED_HOSTS:
  - "{{ inventory_hostname }}" MEDIA_ROOT: "{{ netbox_shared_path }}/media" REPORTS_ROOT: "{{ netbox_shared_path }}/reports" SCRIPTS_ROOT: "{{ netbox_shared_path }}/scripts" netbox_database_host: pg-netbox.idolactiviti.es netbox_database_port: 15432 netbox_database: netbox_prod netbox_database_user: netbox_prod_user netbox_database_password: "very_secure_password_for_prod" netbox_database_maintenance: netbox_prod redis_bind: 127.0.0.1 redis_version: 6.0.9 redis_checksum: sha256:dc2bdcf81c620e9f09cfd12e85d3bc631c897b2db7a55218fd8a65eaa37f86dd

请查看examples/目录以获取更多信息。

== 故障排除

=== uWSGI重置TCP连接当netbox_protocol设置为http时，uWSGI可能会表现出奇怪的行为，并随机重置TCP连接。例如，当使用https://github.com/netbox-community/pynetbox[pynetbox]与API交互时，可能会出现“连接被对等体重置”的错误。如果您受到此问题影响，请尝试将`netbox_protocol`切换为`uwsgi`，并使用负载均衡器，或按以下方式调整您的`netbox_uwsgi_options`。请参见https://github.com/lae/ansible-role-netbox/issues/130#issuecomment-847571006[此GitHub问题]进行相关讨论。