salt-napalm 2019.1.0a2

# 用于 Salt 的 napalm-salt
模块，用于检索、控制、强制执行和更新网络设备的配置

Salt Basics
===========

Salt 新手？查看 [本文档](https://docs.saltstack.com/en/latest/topics/tutorials/walkthrough.html) 以获得简要介绍，以快速了解基础知识。

测试环境
================

在本文档的其余部分，我们将设置一个测试环境来针对路由器运行一些 salt 命令。此测试环境使用运行 Ubuntu 16.04 的 vagrant VM，它充当 salt-master 和 proxy-master，建立并维护与路由器的连接，以便在它们上执行命令。

安装 Salt
=============

安装 Salt 的最简单方法是通过 [salt bootstrap](https://docs.saltstack.com/en/latest/topics/tutorials/salt_bootstrap.html)。这是一个安装示例：

```bash
wget -O bootstrap-salt.sh https://bootstrap.saltstack.com/develop
sudo sh bootstrap-salt.sh
```

这将安装 `salt-minion` 和仅限 `salt-proxy`，但我们也希望此框成为 `salt-master`，因此我们将安装它：

```bash
sudo sh bootstrap-salt.sh -M
```

有关更具体的安装说明，请参阅 Saltstack 官方文档中的 [平台特定说明](https://docs.saltstack.com/en/latest/topics/installation/#platform-specific-installation-instructions)。
请注意**从 PPA repo** 安装主发行版，因为在本地服务器上将作为主服务器运行，将设备作为代理奴才来控制。

CentOS 文档可以在 [这里](centos_installation.md) 找到。

安装 NAPALM
==============

如果您的系统上从未安装过 NAPALM，则需要在 napalm-salt 可以工作之前安装它：
```
sudo apt-get install libffi-dev libssl- dev python-dev python-cffi libxslt1-dev python-pip
sudo pip install --upgrade cffi
sudo pip install napalm-junos napalm-iosxr napalm-ios
```

简单的方法：Salt 用户可以通过单个命令安装 NAPALM，使用 [napalm-install Saltstack 公式](https://github.com/saltstack-formulas/napalm-install-formula)。可以在以下位置找到更详细的使用示例：https://mirceaulinic.net/2017-07-06-napalm-install-formula/。

配置 Salt Proxy（和 Minion）
===================================

使 Salt 运行所需的主要配置文件proxy-master 位于`/etc/salt/proxy`。该文件应该已经存在，尽管您可能需要创建它。

我们需要告诉代理进程本地机器是`salt-master`，并关闭多处理。您可以将以下内容添加到 `/etc/salt/proxy` 文件的顶部：

```
master: localhost
multiprocessing: false
mine_enabled: true # 不需要，但很高兴有
pki_dir: /etc/salt/pki/proxy # 不需要 - 这会将代理密钥分隔到不同的目录
```

此外，您可能需要编辑 `/etc/salt /minion` 文件将主位置指向自身。这不是必需的，但除了路由器之外，它还允许您将 VM 定位为 minion。将此添加到 `/etc/salt/minion` 的顶部：

```
master: localhost
```

配置与设备的连接
==================== ==================

`master` 配置文件期望pillar 位于`/srv/pillar` 中，但是这个目录可能不存在，所以创建它：
```
mkdir -p /srv/pillar
```

要配置将支柱存储在不同的目录中，请参阅 [`pillar_roots`](https://docs.saltstack.com/en/latest/ref/configuration/master.html#pillar-roots)（和 [`file_roots` ](https://docs.saltstack.com/en/latest/ref/configuration/master.html#file-roots)）主配置文件中的配置选项（通常是`/etc/salt/master`或`/srv /master` - 取决于操作系统）。

接下来，我们需要在该目录中创建一个 `top.sls` 文件，该文件告诉 salt-master 哪些 minions 接收哪个支柱。创建并编辑 `/srv/pillar/top.sls` 文件并使其如下所示：

```yaml
base:
[DEVICE_ID]:
- [DEVICE_SLS_FILENAME]
```

其中：

- DEVICE_ID 将是用于与设备交互的名称，来自服务器的 CLI
- DEVICE_SLS_FILENAME 是包含设备规范的文件的名称

示例：

```yaml
base:
router1:
- router1_pillar
```

其中：

- router1 是用于与设备交互的名称：`salt 'router1' test.ping`
- `/srv/pillar/router1_pillar.sls` 是包含此设备规格的文件

**注意这个结构**：注意 `top.sls` 文件的 `- router1_pillar` 部分缺少 `.sls` 扩展名，即使该行期望在同一目录中看到一个名为`router1_pillar.sls`。另外，请注意在引用 `.sls` 文件时不应使用点，因为这将被解释为目录结构。例如，如果您将行配置为 `-router1.pillar`，salt 会在 `/srv/pillar` 目录中查找名为 `router1` 的文件夹，然后在该目录中查找名为 `pillar.sls 的文件`。最后一件事 - 在本例中，我将支柱文件称为“router1_pillar”，以明确表示最后一行引用了支柱文件，但更常见的是将支柱文件称为设备本身的名称，所以：

```yaml
base:
router1:
- router1
```
现在我们已经引用了这个 `router1_pillar` 文件，我们需要创建它并添加支柱。创建并编辑 `/srv/pillar/router1_pillar.sls` 文件并添加以下内容：

```yaml
proxy:
proxytype: napalm
driver: [DRIVER]
host: [HOSTNAME]
username: [USERNAME]
passwd: [PASSWORD]
` ``

其中：

- DRIVER 是连接到设备时要使用的驱动程序。有关支持的操作系统的完整列表，请查看 [NAPALM readthedocs 页面](https://napalm.readthedocs.io/en/latest/#supported-network-operating-systems)
- HOSTNAME、USERNAME、PASSWORD 是连接细节

示例 ```router1_pillar.sls```:

```yaml
proxy:
proxytype: napalm
driver: iosxr
host: 192.168.128.128
username: my_username
passwd: my_password
```

*** 注意：*** 确保支柱是一个有效的 YAML 文件！

此外，使用支柱中提供的凭据仔细检查您是否可以从服务器连接到设备。

如果错误仍然存​​在，请在 Python 控制台中运行以下行并在 [network.toCode()](https: //networktocode.herokuapp.com/):

```python
>>> from napalm_base import get_network_driver
>>> d = get_network_driver('DRIVER')
>>> e = d('HOSTNAME', 'USERNAME', 'PASSWORD', optional_args={'config_lock': False})
>>> e.open()
>>> e.get_facts()
>>> e. close()
```

对于附加参数，可以将它们添加到 `optional_args` 字段中，例如：


```yaml
proxy:
proxytype: napalm
driver: ios
host: 192.168.128.128
username: my_username
passwd: ''
optional_args:
secret : sup3rsek3t
ssh_config_file: ~/custom_ssh_config_file
```

查看 [每个驱动程序的可选参数列表](http://napalm.readthedocs.io/en/develop/support/index.html#list-of-supported-optional-arguments ）。

使用 SSH 密钥进行身份验证时，“passwd”（或“password”、“pass”）字段可以为空，也可以从柱中删除。但是，请注意，并非所有驱动程序都使用基于 SSH 的身份验证。例如，Arista EOS 和 Cisco Nexus 使用基于 HTTP 的 API，因此密码是强制性的！

有关支柱配置的更多详细信息，请参阅 [官方文档](https://docs.saltstack.com/en/develop/ref/proxy/all/salt.proxy.napalm.html) 和 [Salt 下的网络自动化参考文档]（https://docs.saltstack.com/en/develop/topics/network_automation/index.html#napalm）。


启动 Salt 服务
========================

```bash
systemctl start salt-master
systemctl restart salt-minion
```



将代理 minion 作为服务
======================================

要将minion配置为作为服务运行，请创建文件` ``/etc/systemd/system/salt-proxy@.service``` 带有以下内容：

```
[Unit]
Description=Salt proxy minion
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin /salt-proxy -l debug --proxyid=%i
User=root
Group=root
Restart=always
RestartPreventExitStatus=SIGHUP
RestartSec=5

[安装]
WantedBy=default.target
```

根据 salt master 的安装方式，可能需要更改 ```salt-proxy``` 二进制文件的位置。您可以使用 ```which salt-proxy``` 命令查找二进制文件的位置。此外，使用 ```-l debug``` 开关将日志记录级别设置为调试。这对于故障排除很有用，但是您可能希望删除它。

一旦文件被创建并填充 ```systemd``` 将需要使用 ```systemctl daemon-reload``` 重新加载以获取新单元。请注意，重新加载 ```systemd``` 可能会有影响，所以要小心。


为您的设备启动代理 minion
========================================

从测试代理 minion 开始：
```bash
sudo salt-proxy --proxyid=[DEVICE_ID] -l debug
```

在第一次连接尝试时，您会发现该 minion 无法交谈并卡住以下错误消息：
```
[ERROR ] Salt Master 已缓存此节点的公钥，此 salt minion 将等待 10 秒再尝试重新认证
[INFO] 等待 10 秒再重试。
```
这是正常的，是由于主节点不接受来自 minion 的 salt key。使用 <kbd>CTRL</kbd>+<kbd>C</kbd> 退出 minion 并运行 ```sudo salt-key```。在 ```Unaccepted Keys:``` 下你应该看到你的 ```[DEVICE_ID]```。使用 ```sudo salt-key -a [DEVICE_ID]``` 接受密钥。现在重新运行 minion 调试，您应该会看到 minion 连接到您的设备。


测试你的配置
========================

接受密钥后，以调试模式重新启动代理并启动单独的终端会话。在您的新终端中，发出以下命令：
```
sudo salt 'core01.nrt01' test.ping
```
用你的 DEVICE_ID 替换 'core01.nrt01'。输出：
```
core01.nrt01:
True
```
如果没有问题，它应该返回 `True`。如果一切顺利，点击 <kbd>CTRL</kbd>+<kbd>C</kbd> 并重新启动 salt-proxy 作为守护进程。
```
sudo salt-proxy --proxyid=[DEVICE_ID] -d
```
最后，同步你的包：
```
sudo salt core01.nrt01 saltutil.sync_all
```
和以前一样，'core01.nrt01'设备ID。



================

现在一切都设置好了，你只需要开始发出命令来检索/设置属性。

语法：

```bash
salt [DEVICE_ID] [FUNCTION]
```

有关更新的函数列表，请查看以下资源：
- [net](https://docs.saltstack.com/en/develop/ref/modules /all/salt.modules.napalm_network.html#module-salt.modules.napalm_network) 模块
- [ntp](https://docs.saltstack.com/en/develop/ref/modules/all/salt.modules.napalm_ntp .html#module-salt.modules.napalm_ntp) 模块
- [bgp](https://docs.saltstack.com/en/develop/ref/modules/all/salt.modules.napalm_bgp.html#module-salt.modules .napalm_bgp) 模块
- [snmp](https://docs.saltstack.com/en/develop/ref/modules/all/salt.modules.napalm_snmp.html#module-salt.modules.napalm_snmp) 模块
- [路由](https:// /docs.saltstack.com/en/develop/ref/modules/all/salt.modules.napalm_route.html#module-salt.modules.napalm_route) 模块
- [用户](https://docs.saltstack.com/en /develop/ref/modules/all/salt.modules.napalm_users.html#module-salt.modules.napalm_users) 模块
- [探针](https://docs.saltstack.com/en/develop/ref/modules/all /salt.modules.napalm_probes.html#module-salt.modules.napalm_probes) 模块

几个例子：

```bash
salt core01.nrt01 net.arp
salt core01.nrt01 net.mac
salt core01.nrt01 net.lldp
salt core01.nrt01 net.ipaddrs
salt core01.nrt01 net.interfaces
salt core01.nrt01 ntp.peers
salt core01.nrt01 ntp.set_peers 192.168.0.1 172.17.17.1 172.17.17.2
salt core01.nrt01 bgp.config #返回BGP配置
salt core01.nrt01 bgp.neighbors #提供BGP会话的统计信息
salt core01.nrt01 snmp.config
salt core01.nrt01 route.show 1.2.3.4/24 bgp
salt core01.nrt01 probes.config
salt core01.nrt01 probes.results
salt core01.nrt01 net.commit
salt core01.nrt01 net.rollback
```

配置强制
==========================

为了确保整个网络的一致性，[states](https://docs.saltstack.com/en/latest/topics/tutorials/starting_states.html) 是您的朋友。当已经提供了模块时，使用状态非常简单（下一节中的示例，例如 [NTP](https://github.com/napalm-automation/napalm-salt#configuration-enforcement-for-ntp -同行示例））。
已经有几个可用的状态，用于：

- [NTP](https://docs.saltstack.com/en/develop/ref/states/all/salt.states.netntp.html)
- [SNMP](https ://docs.saltstack.com/en/develop/ref/states/all/salt.states.netsnmp.html)
- [用户](https://docs.saltstack.com/en/develop/ref/states/ all/salt.states.netusers.html)
- [探针](https://docs.saltstack.com/en/develop/ref/states/all/salt.states.netntp.html)


NTP 对等方的配置实施（示例）
=========================================== =======

在设备的 Pillar 文件中添加以下行：

```yaml
ntp.peers:
- [PEER1]
- [PEER2]
- ...
```

示例：

```yaml
ntp.peers peers:
- 192.168.0.1
- 172.17.17.1
```

现在，当运行以下命令时，Salt 将检查您的设备上的 NTP 对等点是否按照 Pillar 文件中的指定设置。如果没有，将添加缺少的 NTP 对等点并删除多余的。因此，在操作结束时，设备上配置的 NTP 对等体列表将与 Pillar 中列出的 NTP 对等体匹配。

```重击
salt core01.nrt01 state.sls router.ntp
```

SNMP 配置强制（示例）
============================== ==============

在设备的支柱文件中添加以下行：

```yaml
snmp.config:
contact:<email addr>
location:<location>
community:<community name >
```

示例：

```yaml
snmp.config：
联系人：noc@yourcompany.com
位置：加利福尼亚州圣何塞，美国
社区：超级安全
```

执行如下状态，将更新您的 SNMP 配置设备：

```bash
salt core01.nrt01 state.sls router.snmp
```

预定状态：维护配置更新
============================================= =======

使用状态和[调度程序]的功能（https://docs.saltstack.com/en/latest/ref/states/all/salt.states.schedule.html#management-of -the-salt-scheduler) 你可以确保设备上的配置是一致的和最新的。

是的，您不需要跳进一个框并手动执行命令或添加别名等。您只需要编写 5 行配置：

示例：

在主配置文件中：

```yaml
schedule:
ntp_config:
function ：state.sls
参数：router.ntp
返回者：smtp
天数：1
```

其中：

- ```ntp_config``` 只是计划作业的名称 - 可以是任何东西
- ```function``` - 这是告诉 Salt 一个状态将被执行的方式
- ```args``` - 指定状态的名称
- ```returner``` （可选） - 您可以将状态的输出转发到不同的服务。在这种情况下，SNMP - 将向特定地址发送一封包含状态摘要的电子邮件。有 [许多其他可用的返回者](https://docs.saltstack.com/en/latest/ref/returners/#full-list-of-returners)
- ``days`` - 多久检查一次 &更新配置。其他选项包括：```seconds```、```minutes```、```hours``` 等...


其他模块：
==============

Salt 带有许多不同的模块 - 完整参考 [https://docs.saltstack.com/en/latest/ref/index.html](https://docs.saltstack.com/en/latest/ref/index .html）。

其他功能很少，例如 [reactor](https://docs.saltstack.com/en/latest/topics/reactor/)。反应器系统允许您在事件发生后根据其输出执行命令。

Vagrant：
========
可以使用包含的 Vagrantfile 和 saltstack 目录来自动配置包含 salt
master/minion/proxy 主机和 vEOS 交换机的开发/测试环境。要使用，请从 [www.arista.com](www.arista.com) 下载 vEOS-lab-4.16.9M.box 映像，导入并启动：

```bash
vagrant box add --name vEOS- lab.4.16.9M vEOS-lab-4.16.9M.box
vagrant up
```
这将使用从最新的 git 源构建的 salt-minion 和 salt-master 构建一个 Ubuntu 可信赖的映像，安装 napalm 和 capirca，并
正确配置代理。从那里，使用 `vagrant ssh master` 登录到 master 并运行 salt 命令。如果需要，可以在
运行 `vagrant up` 之前编辑 Vagrantfile 以更改创建的主机数量，或使用自定义 saltstack git 存储库来测试新的 salt 模块。


旧版 NAPALM Salt 安装
=================================

*** 注意：***
这适用于 2016.11.0 之前的 salt 版本。更多详情见：[https://mirceaulinic.net/2016-11-30-salt-carbon-released/](https://mirceaulinic.net/2016-11-30-salt-carbon-released/) . 如果不确定，您可以使用：```salt --versions-report``` 检查 Salt 版本。

首先 git 克隆此存储库并更改为目录：```git clone https://github.com/napalm-automation/napalm-salt.git && cd napalm-salt```。

使用以下命令提取 SPM 存档：```tar xf napalm-2016.11.spm``` 用于 Salt ``>=2016.3`` 或 ```tar xf napalm.spm``` 用于旧版本。解压时，会创建一个名为 ```napalm``` 的目录。

将其所有文件和目录复制到主配置文件中指定为 ```file_roots``` 的路径（默认为 ```/etc/salt/states``），例如 ```cp -r napalm/* /etc/salt/states```。

最后，在 ```file_roots``` 目录下应该有一个类似如下的目录结构（例如：```/etc/salt/states```）：

```
/etc/salt/states
├── top.sls
├── _proxy
| └── napalm.py
├── _modules
| ├── napalm_network.py
| ├── napalm_ntp.py
| ├── napalm_users.py
| ├── napalm_bgp.py
| ├── napalm_route.py
| ├── napalm_snmp.py
| └── napalm_probes.py
├── _grains
| └── napalm.py
├── _states
| ├── netntp.py
| ├── netusers.py
| ├── netsnmp.py
| └── probes.py
├── _runners
| └── ntp.py
├── 路由器
├── init.sls
├── ntp.sls
├── users.sls
├── snmp.sls
└── probes.sls
```