From 98d20fce3a05594b3477e72f00a0ca252a6b8011 Mon Sep 17 00:00:00 2001 From: Denys Havrysh Date: Sat, 12 Mar 2016 17:36:20 +0200 Subject: [PATCH] Correct and reformat README file --- README.rst | 168 ++++++++++++++++++++++++++--------------------------- 1 file changed, 83 insertions(+), 85 deletions(-) diff --git a/README.rst b/README.rst index 82f197a..68798d9 100644 --- a/README.rst +++ b/README.rst @@ -2,36 +2,32 @@ Bootstrapping Salt ================== -Before `Salt`_ can be used for provisioning on the desired machine, the binaries need to be -installed. Since `Salt`_ supports many different distributions and versions of operating systems, -the `Salt`_ installation process is handled by this shell script ``bootstrap-salt.sh``. This -script runs through a series of checks to determine operating system type and version to then +Before `Salt`_ can be used for provisioning on the desired machine, the binaries need to be +installed. Since `Salt`_ supports many different distributions and versions of operating systems, +the `Salt`_ installation process is handled by this shell script ``bootstrap-salt.sh``. This +script runs through a series of checks to determine operating system type and version to then install the `Salt`_ binaries using the appropriate methods. - .. note:: - This ``README`` file is not the absolute truth to what the bootstrap script is capable of, for - that, please read the generated help by passing ``-h`` to the script or even better, `read the + This ``README`` file is not the absolute truth to what the bootstrap script is capable of, for + that, please read the generated help by passing ``-h`` to the script or even better, `read the source`_. +**In case you found a bug, please read** `I found a bug`_ **first before submitting a new issue.** .. _`read the source`: https://github.com/saltstack/salt-bootstrap/blob/develop/bootstrap-salt.sh -**In case you found a bug, please read** `I found a bug`_ **first before submitting a new issue.** - - - Bootstrap ---------- +========= If you're looking for the *one-liner* to install salt, please scroll to the bottom and use the instructions for `Installing via an Insecure One-Liner`_. Examples -~~~~~~~~ +-------- .. note:: @@ -39,6 +35,9 @@ Examples it to ensure that it does what you expect. +Install using curl +~~~~~~~~~~~~~~~~~~ + Using ``curl`` to install latest git: .. code:: console @@ -46,6 +45,30 @@ Using ``curl`` to install latest git: curl -L https://bootstrap.saltstack.com -o install_salt.sh sudo sh install_salt.sh git develop +If you want to install a specific release version (based on the git tags): + +.. code:: console + + curl -o install_salt.sh -L https://bootstrap.saltstack.com + sudo sh install_salt.sh git v2015.8.7 + +To install a specific branch from a git fork: + +.. code:: console + + curl -o install_salt.sh -L https://bootstrap.saltstack.com + sudo sh install_salt.sh -g https://github.com/myuser/salt.git git mybranch + +If all you want is to install a ``salt-master`` using latest git: + +.. code:: console + + curl -o install_salt.sh -L https://bootstrap.saltstack.com + sudo sh install_salt.sh -M -N git develop + + +Install using wget +~~~~~~~~~~~~~~~~~~ Using ``wget`` to install your distribution's stable packages: @@ -54,27 +77,30 @@ Using ``wget`` to install your distribution's stable packages: wget -O install_salt.sh https://bootstrap.saltstack.com sudo sh install_salt.sh - Install a specific version from git using ``wget``: .. code:: console wget -O install_salt.sh https://bootstrap.saltstack.com - sudo sh install_salt.sh -P git v0.16.4 + sudo sh install_salt.sh -P git v2015.8.7 -On the above example we added `-P` which will allow PIP packages to be installed if required but -it's no a necessary flag for git based bootstraps. +.. note:: + + On the above example we added `-P` which will allow PIP packages to be installed if required but + it's no a necessary flag for git based bootstraps. -If you already have python installed, ``python 2.6``, then it's as easy as: +Install using Python +~~~~~~~~~~~~~~~~~~~~ + +If you already have Python installed, ``python 2.6``, then it's as easy as: .. code:: console python -m urllib "https://bootstrap.saltstack.com" > install_salt.sh sudo sh install_salt.sh git develop - -All python versions should support the following one liner: +All Python versions should support the following one liner: .. code:: console @@ -82,7 +108,10 @@ All python versions should support the following one liner: sudo sh install_salt.sh git develop -On a FreeBSD base system you usually don't have either of the above binaries available. You **do** +Install using fetch +~~~~~~~~~~~~~~~~~~~ + +On a FreeBSD base system you usually don't have either of the above binaries available. You **do** have ``fetch`` available though: .. code:: console @@ -109,34 +138,6 @@ Or link them to the right place: ln -s /usr/local/share/certs/ca-root-nss.crt /etc/ssl/cert.pem -If all you want is to install a ``salt-master`` using latest git: - -.. code:: console - - curl -o install_salt.sh -L https://bootstrap.saltstack.com - sudo sh install_salt.sh -M -N git develop - - -If you want to install a specific release version (based on the git tags): - -.. code:: console - - curl -o install_salt.sh -L https://bootstrap.saltstack.com - sudo sh install_salt.sh git v0.16.4 - - -To install a specific branch from a git fork: - -.. code:: console - - curl -o install_salt.sh -L https://bootstrap.saltstack.com - sudo sh install_salt.sh -g https://github.com/myuser/salt.git git mybranch - - -Any of the example above which use two-lines can be made to run in a single-line -configuration with minor modifications, see `Installing via an Insecure One-Liner`_. - - Installing via an Insecure One-Liner ------------------------------------ @@ -147,10 +148,6 @@ The following examples illustrate how to install Salt via a one-liner. Warning! These methods do not involve a verification step and assume that the delivered file is trustworthy. - -Examples -~~~~~~~~ - Installing the latest stable release of Salt (default): .. code:: console @@ -170,8 +167,21 @@ Installing the latest develop branch of Salt: curl -L https://bootstrap.saltstack.com | sudo sh -s -- git develop -Adding support for other operating systems +Unsupported Distro +------------------ + +You found a Linux distribution which we still do not support or we do not correctly identify? +Please run the following commands and report their output when creating a ticket: + +.. code:: console + + sudo find /etc/ -name \*-release -print -exec cat {} \; + command lsb_release -a + + +Adding Support for Other Operating Systems ------------------------------------------ + In order to install salt for a distribution you need to define: 1. To Install Dependencies, which is required, one of: @@ -186,7 +196,7 @@ In order to install salt for a distribution you need to define: install__deps -2. Optionally, define a minion configuration function, which will be called if the +2. Optionally, define a minion configuration function, which will be called if the ``-c|config-dir`` option is passed. One of: .. code:: bash @@ -200,7 +210,7 @@ In order to install salt for a distribution you need to define: config_salt [THIS ONE IS ALREADY DEFINED AS THE DEFAULT] -3. Optionally, define a salt master pre-seed function, which will be called if the -k (pre-seed +3. Optionally, define a salt master pre-seed function, which will be called if the -k (pre-seed master keys) option is passed. One of: .. code:: bash @@ -249,7 +259,7 @@ In order to install salt for a distribution you need to define: .. admonition:: Attention! - The start daemons function should be able to restart any daemons which are running, or start if + The start daemons function should be able to restart any daemons which are running, or start if they're not running. @@ -280,7 +290,7 @@ In order to install salt for a distribution you need to define: ---- -Below is an example for Ubuntu Oneiric(the example may not be up to date with the script): +Below is an example for Ubuntu Oneiric (the example may not be up to date with the script): .. code:: bash @@ -328,8 +338,8 @@ Below is an example for Ubuntu Oneiric(the example may not be up to date with th Since there is no ``install_ubuntu_11_10_stable()`` it defaults to the unspecified version script. -The bootstrapping script must be plain POSIX sh only, **not** bash or another shell script. By -design the targeting for each operating system and version is very specific. Assumptions of +The bootstrapping script must be plain POSIX sh only, **not** bash or another shell script. By +design the targeting for each operating system and version is very specific. Assumptions of supported versions or variants should not be made, to avoid failed or broken installations. Supported Operating Systems @@ -344,10 +354,9 @@ Supported Operating Systems - Linaro - Linux Mint 13/14 - OpenSUSE 12/13 -- Oracle Linux 5/5 -- Red Hat 5/6 -- Red Hat Enterprise 5/6 -- Scientific Linux 5/6 +- Oracle Linux 5/6/7 +- Red Hat Enterprise Linux 5/6/7 +- Scientific Linux 5/6/7 - SmartOS - SUSE Linux Enterprise 11 SP1/11 SP2/11 SP3 - Ubuntu 10.x/11.x/12.x/13.x/14.x/15.04 @@ -355,11 +364,11 @@ Supported Operating Systems -I found a bug -------------- +I Found a Bug +============= -If you found a possible problem, or bug, please try to bootstrap using the develop version. The -issue you are having might have already been fixed and it's just not yet included in the stable +If you found a possible problem, or bug, please try to bootstrap using the develop version. The +issue you are having might have already been fixed and it's just not yet included in the stable version. .. code:: console @@ -378,34 +387,23 @@ Or the insecure one liner: If after trying this, you still see the same problems, then, please `file an issue`_. - .. _`Salt`: http://saltstack.org/ .. _`file an issue`: https://github.com/saltstack/salt-bootstrap/issues/new -Unsupported Distro ------------------- - -You found a Linux distribution which we still do not support or we do not correctly identify? -Please run the following commands and report their output when creating a ticket: - -.. code:: console - - sudo find /etc/ -name '*-release' -print -exec cat {} \; - command lsb_release -a - - Testing in Vagrant ------------------- -You can use Vagrant_ to easily test changes on a clean machine. The ``Vagrantfile`` defaults to an +================== + +You can use Vagrant_ to easily test changes on a clean machine. The ``Vagrantfile`` defaults to an Ubuntu box. First, install Vagrant, then: .. code:: console - $ vagrant up - $ vagrant ssh + vagrant up + vagrant ssh .. _Vagrant: http://www.vagrantup.com .. _Installing via an Insecure One-Liner: #installing-via-an-insecure-one-liner + .. vim: fenc=utf-8 spell spl=en cc=100 tw=99 fo=want sts=2 sw=2 et