diff --git a/AUTHORS b/AUTHORS index b743346d..7c86e466 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,11 +1,18 @@ Abishek Raju +Amin Mosayyebzadeh Andrew Mohn George Silvis, III +Ian Ballou Ian Denhardt Igibek Koishybayev Jay Hennessey +(Jethro) Shuwen Sun Jonathan Bell +Kristi Nikolla +Kyle Hogan Logan Bernard +Lucas Xu +Naved Ansari Orran Krieger Peter Desnoyers Ritesh Singh diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst index 0eb65c04..137ac2a2 100644 --- a/docs/INSTALL.rst +++ b/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 `_, edit @@ -48,29 +48,25 @@ 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: @@ -78,16 +74,16 @@ 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! diff --git a/docs/USING.rst b/docs/USING.rst index 487a996a..c679686d 100644 --- a/docs/USING.rst +++ b/docs/USING.rst @@ -60,25 +60,21 @@ been run succesfully. Usage examples --------------- -Included herewith are some examples about +Included here with are some examples about - * Interacting with HIL API directly using the curl utility. - - * And using equivalent cli calls are also included. - -:: - - hil node_register ipmi dummyNode01 ipmiHost4node-01 ipmiUser4node-01 ipmiPass4node-01 +* Interacting with HIL API directly using the curl utility. +* And using equivalent cli calls are also included. 1) Register a switch with HIL: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Eg> Switch name: mockswitch01 - Host name: switchhost01 - User name: switchuser01 - Password: password1234 +- **Switch name:** mockswitch01 +- **Switch type:** mock +- **Host name:** switchhost01 +- **User name:** switchuser01 +- **Password:** password1234 api call @@ -94,36 +90,99 @@ cli call :: - hil switch_register mockswitch02 mock switchhost01 switchuser01 password1234 + $ hil switch_register mockswitch02 mock switchhost01 switchuser01 password1234 2) Registering a Node which uses IPMI for out of band management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - **Node name:** dummyNoderHIL-02 - - **Ipmi info:** - + **hostname:** ipmiHost4node-02 - + **ipmi_username:** ipmiUser4node-02 - + **ipmi_password:** ipmiPass4node-02 +- **Node name:** dummyNoderHIL-02 +- **Ipmi info:** + + **hostname:** ipmiHost4node-02 + + **ipmi_username:** ipmiUser4node-02 + + **ipmi_password:** ipmiPass4node-02 For nodes using IPMI use the following api call: - :: - curl -X PUT http://127.0.0.1:5001/node/dummyNode01 -d ' - > {"obm": { "type": "http://schema.massopencloud.org/haas/v0/obm/ipmi", - > "host": "ipmiHost4node-01", - > "user": "ipmiUser4node-01", - > "password": "ipmiPass4node-01" - > }}' + curl -X PUT http://127.0.0.1:5001/node/dummyNode01 -d ' + > {"obm": { "type": "http://schema.massopencloud.org/haas/v0/obm/ipmi", + > "host": "ipmiHost4node-01", + > "user": "ipmiUser4node-01", + > "password": "ipmiPass4node-01" + > }}' Corresponding cli calls will be as follows: +:: + + $ hil node_register ipmi dummyNode01 ipmiHost4node-01 ipmiUser4node-01 ipmiPass4node-01 + +3) Creating a Project in HIL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +- **Project name:** mockproject01 + +api call + +:: + + curl -X put http://127.0.0.1:5000/project/mockproject01 + +cli call + +:: + + $ hil project_create mockproject01 + +4) Register a node in HIL +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +- **Node name:** mocknode01 +- **Node type:** mock +- **Host name:** mockhost01 +- **User name:** nodeuser01 +- **Password:** password1234 + +api call + +:: + + curl -X put http://127.0.0.1:5000/node/mocknode01 -d ' + > {"type": "http://schema.massopencloud.org/haas/v0/nodes/mock", + > "hostname": "mockhost01", + > "username": "nodeuser01", + > "password": "password1234"}' + +cli call :: - hil node_register ipmi dummyNode01 ipmiHost4node-01 ipmiUser4node-01 ipmiPass4node-01 + $ hil node_register mocknode01 mock mockhost01 nodeuser01 password1234 +4) Creating a Network in HIL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- **Network name:** mocknetwork01 +- **owner:** admin +- **access:** mockproject +- **net_id:** 101 + +api call + +:: + + curl -X put http://127.0.0.1:5000/network/mocknetwork01 -d ' + {"owner": "admin", + "access": "mockproject", + "net_id": "101"}' + +cli call + +:: + + $ hil network_create mocnetwork01 admin mockproject 101 diff --git a/docs/client-library.md b/docs/client-library.md new file mode 100644 index 00000000..0aae87de --- /dev/null +++ b/docs/client-library.md @@ -0,0 +1,28 @@ +# HIL Client Library + +## Description +The HIL API Client Library for Python is designed for Python client-application developers. It offers simple access to HIL APIs. + +## How to Install HIL Modules? +``` +$ pip install git+https://github.com/cci-moc/hil +``` + +## How to Get Started? +``` +import os +from hil.client.client import Client, RequestsHTTPClient + +ep = os.environ.get('HIL_ENDPOINT') +basic_username = os.getenv('HIL_USERNAME') +basic_password = os.getenv('HIL_PASSWORD') + +http_client = RequestsHTTPClient() +http_client.auth = (basic_username, basic_password) +C = Client(ep, http_client) +print C.project.create("test-project") + +``` + +## More Examples. +[leasing script](https://github.com/CCI-MOC/hil/blob/master/examples/leasing/node_release_script.py)