Merge pull request #951 from xuhang57/docs-cleanup

DOCS MATTER!

AUTHORS

@@ -1,11 +1,18 @@
 Abishek Raju <abishek.raju@gmail.com>
+Amin Mosayyebzadeh <mosayyeb@bu.edu>
 Andrew Mohn <AndrewMohn@gmail.com>
 George Silvis, III <george.iii.silvis@gmail.com>
+Ian Ballou <ianballou67@gmail.com>
 Ian Denhardt <ian@zenhack.net>
 Igibek Koishybayev <koishybayev.igibek@gmail.com>
 Jay Hennessey <henn@users.sourceforge.net>
+(Jethro) Shuwen Sun <http://orcid.org/0000-0001-6811-8310>
 Jonathan Bell <jbell@bu.edu>
+Kristi Nikolla <knikolla@massopen.cloud>
+Kyle Hogan <klhogan@bu.edu>
 Logan Bernard <bernard.logan4@gmail.com>
+Lucas Xu <xuh@massopen.cloud>
+Naved Ansari <naved001@gmail.com>
 Orran Krieger <okrieg@yahoo.com>
 Peter Desnoyers <pjd@ccs.new.edu>
 Ritesh Singh <ritesh277coe@gmail.com>

docs/INSTALL.rst

@@ -16,11 +16,11 @@ Prerequisite Software
 HIL requires a number of packages available through the CentOS RPM
 repositories, as well as the EPEL repository. EPEL can be enabled via::
 
-    yum install epel-release
+    $ yum install epel-release
 
 Then, the rest of the packages can be installed via::
 
-    yum install libvirt bridge-utils ipmitool telnet httpd mod_wsgi python-pip qemu-kvm python-virtinst virt-install python-psycopg2 vconfig net-tools
+    $ yum install libvirt bridge-utils ipmitool telnet httpd mod_wsgi python-pip qemu-kvm python-virtinst virt-install python-psycopg2 vconfig net-tools
 
 In addition, HIL depends on a number of python libraries. Many of these are
 available as RPMs as well, but we recommend installing them with pip, since
@@ -35,7 +35,7 @@ The setup described in this document runs into problems with SELinux. In the
 future, we hope to ship a set of SELinux security policies with HIL, but for
 now the solution is to disable SELinux::
 
-    sudo setenforce 0
+    $ sudo setenforce 0
 
 Make sure SELinux is also disabled on startup. To do this `on
 CentOS/RHEL <https://wiki.centos.org/HowTos/SELinux>`_, edit
@@ -48,46 +48,42 @@ to
 SELINUX=permissive
 ```
 
-User need to choose appropriate values for their environment:
+User needs to choose appropriate values for their environment:
 -------------------------------------------------------------
 
 For simplicity we have provided default values:
 Copy the following lines in file ``hil_env``
 
-        HIL_USER=hil
+        export HIL_USER=hil
 
-        HIL_DB_ROLE=hil
+        export HIL_ADMIN=hil
 
-        HIL_DB_PASSWORD=secret
+        export HIL_ADMIN_PASSWORD=secret
 
-        HIL_ADMIN=hil
-
-        HIL_ADMIN_PASSWORD=secret
-
-        HIL_HOME_DIR=/var/lib/hil
+        export HIL_HOME_DIR=/var/lib/hil
 
 
 
 Before starting this procedure do::
 
-        source hil_env
+        $ source hil_env
 
 
 Setting up system user for HIL:
 --------------------------------
 
 First create a system user ``${HIL_USER}`` with::
 
-  sudo useradd --system ${HIL_USER} -d /var/lib/hil -m -r
+  $ sudo useradd --system ${HIL_USER} -d /var/lib/hil -m -r
 
 
 The HIL software itself can then be installed as root by running::
 
-    sudo su -
-    cd /root
-    git clone https://github.com/CCI-MOC/hil
-    cd hil
-    sudo python setup.py install
+    $ sudo su -
+    $ cd /root
+    $ git clone https://github.com/CCI-MOC/hil
+    $ cd hil
+    $ python setup.py install
 
 
 hil.cfg
@@ -115,12 +111,12 @@ permissions should be set to read-only and ownership set to ``${HIL_USER}``
 From source directory of hil as user root do the following::
 
     (from /root/hil)
-    cp examples/hil.cfg /etc/hil.cfg
-    chown ${HIL_USER}:${HIL_USER} hil.cfg
-    chmod 400 hil.cfg
+    $ cp examples/hil.cfg /etc/hil.cfg
+    $ chown ${HIL_USER}:${HIL_USER} hil.cfg
+    $ chmod 400 hil.cfg
     (run following command as ${HIL_USER} from ${HIL_HOME_DIR}
-    su - ${HIL_USER}
-    ln -s /etc/hil.cfg .
+    $ su - ${HIL_USER}
+    $ ln -s /etc/hil.cfg .
 
 Authentication and Authorization
 --------------------------------
@@ -175,14 +171,14 @@ provides one way to accomplish this.
 To create the database tables, first make sure ``hil.cfg`` is set up the way
 you need, including any extensions you plan to use, then::
 
-    sudo -i -u ${HIL_USER}; hil-admin db create
+  $ sudo -i -u ${HIL_USER}; hil-admin db create
 
 If the authorization backend activated in ``hil.cfg`` is  ``hil.ext.auth.database =``
 then you will need to add an initial user with administrative privileges to the
 database in order to bootstrap the system.
 You can do this by running the following command (as user ``hil``)::
 
-  sudo -i -u ${HIL_USER}; hil create_admin_user ${HIL_ADMIN_USER} ${HIL_ADMIN_PASSWORD}
+  $ sudo -i -u ${HIL_USER}; hil create_admin_user ${HIL_ADMIN_USER} ${HIL_ADMIN_PASSWORD}
 
 You can then create additional users via the HTTP API. You may want to
 subsequently delete the initial user; this can also be done via the API.
@@ -191,7 +187,7 @@ subsequently delete the initial user; this can also be done via the API.
 
 All HIL commands in these instructions should be run in this directory::
 
-  cd /var/lib/hil
+  $ cd /var/lib/hil
 
 Networking - Bridges
 --------------------
@@ -241,21 +237,21 @@ Starting the service:
 ^^^^^^^^^^^^^^^^^^^^^
 
 Following commands will start the daemon:
-``systemctl daemon-reload``
-``systemctl start create_bridges.service``
+``$ systemctl daemon-reload``
+``$ systemctl start create_bridges.service``
 
 You can check the status using:
-``systemctl status create_bridges.service``
+``$ systemctl status create_bridges.service``
 
 To auto-start the service on boot (recommended):
-``systemctl enable create_bridges.service``
+``$ systemctl enable create_bridges.service``
 
 For systems that do not support systemd:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can add the following line::
 
-  (cd /etc && create_bridges)
+  ($ cd /etc && create_bridges)
 
 to the end of ``/etc/rc.local``.
 
@@ -280,16 +276,16 @@ uncomment the following lines::
 
 Then create the group 'libvirt' and add the HIL user to that group::
 
-  sudo groupadd libvirt
-  sudo gpasswd libvirt -a hil
+  $ sudo groupadd libvirt
+  $ sudo gpasswd libvirt -a hil
 
 Finally, restart ``libvirt`` with::
 
-  sudo service libvirtd restart
+  $ sudo service libvirtd restart
 
 You should also set libvirt to start on boot::
 
-  sudo chkconfig libvirtd on
+  $ sudo chkconfig libvirtd on
 
 Headnode image
 ^^^^^^^^^^^^^^
@@ -312,8 +308,8 @@ The directory specified by path must already exist, and be readable and
 writable by the ``libvirt`` user. Then activate the pool, and make the it
 activate on boot, with::
 
-  virsh --connect qemu:///system pool-start hil_headnodes
-  virsh --connect qemu:///system pool-autostart hil_headnodes
+  $ virsh --connect qemu:///system pool-start hil_headnodes
+  $ virsh --connect qemu:///system pool-autostart hil_headnodes
 
 The scripts in ``examples/cloud-img-with-passwd`` can be used to build
 an ubuntu 14.04 or centos 7 disk image with a default root password. Read
@@ -322,11 +318,11 @@ the README in that directory for more information.
 Once the disk image is built, copy ito the storage pool directory (here we
 assume it is called ``base.img``)::
 
-  mv base.img /var/lib/libvirt/images/
+  $ mv base.img /var/lib/libvirt/images/
 
 Finally, create the base headnode with::
 
-  virsh --connect qemu:///system define base.xml
+  $ virsh --connect qemu:///system define base.xml
 
 where ``base.xml`` contains a description of the headnode::
 
@@ -423,18 +419,18 @@ following directive will have to be turned on
 
 If you haven't already, create the directory that will contain the HIL WSGI module::
 
- sudo mkdir /var/www/hil/
+  $ sudo mkdir /var/www/hil/
 
 Copy the file ``hil.wsgi`` from the top of the hil source tree to the
 location indicated by the ``WSGIScriptAlias`` option. The virtual host and
 server name should be set according to the hostname (and port) by which clients
 will access the api. Then, restart Apache::
 
-  sudo service httpd restart
+  $ sudo service httpd restart
 
 You should also set apache to start on boot::
 
-  sudo chkconfig httpd on
+  $ sudo chkconfig httpd on
 
 Running the network server:
 ---------------------------
@@ -465,14 +461,14 @@ Starting the service:
 ---------------------
 
 Following commands will start the daemon:
-``systemctl daemon-reload``
-``systemctl start hil_network``
+``$ systemctl daemon-reload``
+``$ systemctl start hil_network``
 
 You can check the status using:
-``systemctl status hil_network``
+``$ systemctl status hil_network``
 
 To auto-start the service on boot:
-``systemctl enable hil_network``
+``$ systemctl enable hil_network``
 
 
 For systems that do not support systemd:
@@ -482,11 +478,11 @@ It uses "Upstart" an equivalent of systemd to manage its daemons/processes.
 
 For such systems, the networking server may be started as the HIL user by running::
 
-  hil serve_networks &
+  $ hil serve_networks &
 
 To make this happen on boot, add the following to ``/etc/rc.local``::
 
-  (cd /var/lib/hil && su hil -c 'hil serve_networks') &
+  ($ cd /var/lib/hil && su hil -c 'hil serve_networks') &
 
 
 HIL Client:
@@ -506,8 +502,8 @@ Create a file ``client_env`` with following entries::
 
 To get started with HIL from your home dir do the following::
 
-    source client_env
-    hil list_nodes all
+    $ source client_env
+    $ hil list_nodes all
 
 If you get an empty list ``[]`` as output then congratulations !!
 At this point, you should have a functional HIL service running!