mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 08:58:59 +00:00
246 lines
8.5 KiB
ReStructuredText
246 lines
8.5 KiB
ReStructuredText
.. _introduction:
|
|
|
|
Introduction
|
|
============
|
|
|
|
Salt was added to the FreeBSD ports tree Dec 26th, 2011 by Christer Edwards
|
|
<christer.edwards@gmail.com>. It has been tested on FreeBSD 8.2 and 9.0RC
|
|
releases.
|
|
|
|
Salt is dependent on the following additional ports. These will be installed as
|
|
dependencies of the ``sysutils/salt`` port::
|
|
|
|
/devel/py-yaml
|
|
/devel/py-pyzmq
|
|
/devel/py-Jinja2
|
|
/security/py-pycrypto
|
|
/security/py-m2crypto
|
|
|
|
.. _installation:
|
|
|
|
Installation
|
|
============
|
|
|
|
To install Salt from the FreeBSD ports tree, use the command::
|
|
|
|
cd /usr/ports/sysutils/salt && make install clean
|
|
|
|
Once the port is installed you'll need to make a few configuration changes.
|
|
These include defining the IP to bind to (optional), and some configuration
|
|
path changes to make salt fit more natively into the FreeBSD filesystem tree.
|
|
|
|
.. _configuration:
|
|
|
|
Configuration
|
|
=============
|
|
|
|
In the sections below I'll outline configuration options for both the Salt
|
|
Master and Salt Minions.
|
|
|
|
The Salt port installs two sample configuration files, salt/master.sample and
|
|
salt/minion.sample (these should be installed in /usr/local/etc/, unless you use a
|
|
different %%PREFIX%%). You'll need to copy these .sample files into place and
|
|
make a few edits. First, copy them into place as seen here::
|
|
|
|
cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master
|
|
cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion
|
|
|
|
Note: You'll only need to copy the config for the service you're going to run.
|
|
|
|
Once you've copied the config into place you'll need to make changes specific
|
|
to your setup. Below I'll outline suggested configuration changes to the
|
|
Master, after which I'll outline configuring the Minion.
|
|
|
|
.. _master_configuration:
|
|
|
|
Master Configuration
|
|
====================
|
|
|
|
This section outlines configuration of a Salt Master, which is used to control
|
|
other machines known as "minions" (see "Minion Configuration" for instructions
|
|
on configuring a minion). This will outline IP configuration, and a few key
|
|
configuration paths.
|
|
|
|
**Interface**
|
|
|
|
By default the Salt master listens on ports 4505 and 4506 on all interfaces
|
|
(0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the
|
|
"interface" directive as seen here::
|
|
|
|
- #interface: 0.0.0.0
|
|
+ interface: 10.0.0.1
|
|
|
|
**pki_dir**
|
|
|
|
Salt is primarily developed on Linux, and as such carries some Linux-isms in
|
|
its development and configuration. These are all very easily remedied to more
|
|
seamlessly fit into FreeBSD. One such configuration option is the *pki_dir:*
|
|
directive. To ensure all of Salts files end up where you expect, you'll likely
|
|
want to update this line as seen here::
|
|
|
|
- #pki_dir: /etc/salt/pki
|
|
+ pki_dir: /usr/local/etc/salt/pki
|
|
|
|
**file_roots**
|
|
|
|
Finally, if you plan on using Salts state-management features, you'll want to
|
|
update the *file_roots:* directive. This directive defines the location of the
|
|
state files. I suggest updating this directive as seen here::
|
|
|
|
- #file_roots:
|
|
- # base:
|
|
- # - /srv/salt
|
|
+ file_roots:
|
|
+ base:
|
|
+ - /usr/local/etc/salt/states
|
|
|
|
**rc.conf**
|
|
|
|
Last but not least you'll need to activate the Salt Master in your rc.conf
|
|
file. Using your favorite editor, open /etc/rc.conf or /etc/rc.conf.local and
|
|
add this line::
|
|
|
|
+ salt_master_enable="YES"
|
|
|
|
Once you've completed all of these steps you're ready to start your Salt
|
|
Master. The Salt port installs an rc script which should be used to manage your
|
|
Salt Master. You should be able to start your Salt Master now using the command
|
|
seen here::
|
|
|
|
service salt_master start
|
|
|
|
If your Salt Master doesn't start successfully, go back through each step and
|
|
see if anything was missed. Salt doesn't take much configuration (part of its
|
|
beauty!), and errors are usually simple mistakes.
|
|
|
|
.. _ minion_configuration:
|
|
|
|
Minion Configuration
|
|
====================
|
|
|
|
Configuring a Salt Minion is surprisingly simple. Unless you have a real need
|
|
for customizing your minion configuration (which there are plenty of options if
|
|
you are so inclined!), there is one simple directive that needs to be updated.
|
|
That option is the location of the master.
|
|
|
|
By default a Salt Minion will try to connect to the dns name "salt". If you
|
|
have the ability to update DNS records for your domain you might create an A or
|
|
CNAME record for "salt" that points to your Salt Master. If you are able to do
|
|
this you likely can do without any minion configuration at all.
|
|
|
|
If you are not able to update DNS, you'll simply need to update one entry in
|
|
the configuration file. Using your favorite editor, open the minion
|
|
configuration file and update the "master" entry as seen here::
|
|
|
|
- #master: salt
|
|
+ master: 10.0.0.1
|
|
|
|
Simply update the master directive to the IP or hostname of your Salt Master.
|
|
Save your changes and you're ready to start your Salt Minion. Advanced
|
|
configuration options are covered in another chapter.
|
|
|
|
**pki_dir**
|
|
|
|
Salt is primarily developed on Linux, and as such carries some Linux-isms in
|
|
its development and configuration. These are all very easily remedied to more
|
|
seamlessly fit into FreeBSD. One such configuration option is the *pki_dir:*
|
|
directive. To ensure all of Salts files end up where you expect, you'll likely
|
|
want to update this line as seen here::
|
|
|
|
- #pki_dir: /etc/salt/pki
|
|
+ pki_dir: /usr/local/etc/salt/pki
|
|
|
|
**rc.conf**
|
|
|
|
Before you're able to start the Salt Minion you'll need to update your rc.conf
|
|
file. Using your favorite editor open /etc/rc.conf or /etc/rc.conf.local and
|
|
add this line::
|
|
|
|
+ salt_minion_enable="YES"
|
|
|
|
Once you've completed all of these steps you're ready to start your Salt
|
|
Minion. The Salt port installs an rc script which should be used to manage your
|
|
Salt Minion. You should be able to start your Salt Minion now using the command
|
|
seen here::
|
|
|
|
service salt_minion start
|
|
|
|
If your Salt Minion doesn't start successfully, go back through each step and
|
|
see if anything was missed. Salt doesn't take much configuration (part of its
|
|
beauty!), and errors are usually simple mistakes.
|
|
|
|
.. _tying_it_all_together:
|
|
|
|
Tying It All Together
|
|
======================
|
|
|
|
If you've successfully completed each of the steps above you should have a
|
|
running Salt Master and a running Salt Minion. The Minion should be configured
|
|
to point to the Master. To verify that there is communication flowing between
|
|
the Minion and Master we'll run a few initial ``salt`` commands. These commands
|
|
will validate the Minions RSA encryption key, and then send a test command to
|
|
the Minion to ensure that commands and responses are flowing as expected.
|
|
|
|
**Key Management**
|
|
|
|
Salt uses AES encryption for all communication between the Master and the
|
|
Minion. This ensures that the commands you send to your Minions (your cloud)
|
|
can not be tampered with, and that communication between Master and Minion is
|
|
only done through trusted, accepted keys.
|
|
|
|
Before you'll be able to do any remote execution or state management you'll
|
|
need to accept any pending keys on the Master. Run the ``salt-key`` command to
|
|
list the keys known to the Salt Master::
|
|
|
|
[root@master ~]# salt-key -L
|
|
Unaccepted Keys:
|
|
avon
|
|
bodie
|
|
bubbles
|
|
marlo
|
|
Accepted Keys:
|
|
|
|
This example shows that the Salt Master is aware of four Minions, but none of
|
|
the keys have been accepted. To accept the keys and allow the Minions to be
|
|
controlled by the Master, again use the ``salt-key`` command::
|
|
|
|
[root@master ~]# salt-key -A
|
|
[root@master ~]# salt-key -L
|
|
Unaccepted Keys:
|
|
Accepted Keys:
|
|
avon
|
|
bodie
|
|
bubbles
|
|
marlo
|
|
|
|
The ``salt-key`` command allows for signing keys individually or in bulk. The
|
|
example above, using ``-A`` bulk-accepts all pending keys. To accept keys
|
|
individually use the lowercase of the same option, ``-a keyname``.
|
|
|
|
.. _sending_commands:
|
|
|
|
Sending Commands
|
|
================
|
|
|
|
Everything should be set for you to begin remote management of your Minions.
|
|
Whether you have a few or a few-dozen, Salt can help you manage them easily!
|
|
|
|
For final verification, send a test function from your Salt Master to your
|
|
minions. If all of your minions are properly communicating with your Master,
|
|
you should "True" responses from each of them. See the example below to send
|
|
the ``test.ping`` remote command::
|
|
|
|
[root@avon ~]# salt '*' test.ping
|
|
{'avon': True}
|
|
|
|
.. _where_do_i_go_from_here:
|
|
|
|
Where Do I Go From Here
|
|
========================
|
|
|
|
Congratulations! You've successfully configured your first Salt Minions and are
|
|
able to send remote commands. I'm sure you're eager to learn more about what
|
|
Salt can do. Depending on the primary way you want to manage your machines you
|
|
may either want to visit the section regarding Salt States, or the section on
|
|
Modules.
|