diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9b46494..e9d2b2d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,16 +1,5 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps in this page: +If you would like to contribute to the development of this project. - http://docs.openstack.org/infra/manual/developers.html +Submit your pull request and issues to https://github.com/uggla/python-redfish . -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: - - http://docs.openstack.org/infra/manual/developers.html#development-workflow - -Pull requests submitted through GitHub will be ignored. - -Bugs should be filed on Launchpad, not GitHub: - - https://bugs.launchpad.net/python-redfish +You can also share and discuss on the mailing list as well. diff --git a/README.rst b/README.rst index 3491806..f770807 100644 --- a/README.rst +++ b/README.rst @@ -41,23 +41,38 @@ are discouraged due to security. Python requirements are listed in requirements.txt; additional requirements for running the unit test suite are listed in test-requirements.txt. -Developer setup +Get the sources --------------- -To initialize a local development environment (eg, so you can run unit tests) -you should run the following commands +The sources are available on github and can be retrieve using:: + + git clone https://github.com/uggla/python-redfish + +As python redefish is currently in heavy development we recommend to checkout the devel branch using:: + + cd python-redfish + git checkout devel + +Installation +------------ + +Please refer to the following link. + +http://pythonhosted.org/python-redfish/installation.html Contacts -------- -Distribution list : python-redfish@mondorescue.org +Distribution list: python-redfish@mondorescue.org Further References ------------------ +The specification can be found here : + http://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.0.1.pdf + The data model documentation can be found here: - http://www.redfishspecification.org/redfish-data-model-and-schema/ + http://redfish.dmtf.org/schemas/ The overall protocol documentation can be found here: - http://www.redfishspecification.org/ - + http://www.dmtf.org/standards/redfish diff --git a/doc/source/develsetup.rst b/doc/source/develsetup.rst new file mode 100644 index 0000000..551a3fd --- /dev/null +++ b/doc/source/develsetup.rst @@ -0,0 +1,8 @@ +=============== +Developer setup +=============== + +#. Follow `get the sources `_ section to retrieve the sources. +#. Follow `using pip and virtualenv `_ section to create your environment. + +You can start hacking the code now. diff --git a/doc/source/help.rst b/doc/source/help.rst new file mode 100644 index 0000000..e229349 --- /dev/null +++ b/doc/source/help.rst @@ -0,0 +1,12 @@ +============= +Help required +============= + +We need help on the following topic: + +- debian/ubuntu dependencies packaging. +- python3 testing. +- installation on distributions which are not Fedora or Mageia. +- documentation. + +Any contribution will be welcomed. diff --git a/doc/source/images/simulator.jpg b/doc/source/images/simulator.jpg new file mode 100644 index 0000000..6a47144 Binary files /dev/null and b/doc/source/images/simulator.jpg differ diff --git a/doc/source/index.rst b/doc/source/index.rst index af8520f..3897497 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,8 +14,10 @@ Contents: readme installation usage - contributing + develsetup classesdoc + contributing + help Indices and tables ================== diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 41ac939..2ea059d 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -2,11 +2,222 @@ Installation ============ -At the command line:: +Using pip +--------- +Use:: - $ pip install python-redfish + sudo pip install python-redfish -Or, if you have virtualenvwrapper installed:: +Pip will install : + +1. The library and all dependencies into your site-packages directory +2. Redfish client master conf file into /etc/redfish_client.conf +3. Data file (templates) into /usr/share/redfish-client/templates + +Point 2 and 3 above need root access to your system. If you don't have root +access on your system, please follow `Using pip and virtualenv`_ section. + + +Using pip and virtualenv +------------------------ + +1. Install virtualenv and virtualenvwrapper: + + Fedora 22:: + + dnf install python-virtualenv.noarch python-virtualenvwrapper.noarch + + Ubuntu 15.04:: + + apt-get install python-virtualenv virtualenvwrapper + +2. Source virtualenvwrapper.sh:: + + . /usr/bin/virtualenvwrapper.sh + + or:: + + . /usr/share/virtualenvwrapper/virtualenvwrapper.sh + +3. Create a redfish virtual environement:: + + mkvirtualenv redfish + +4. Install using pip:: + + pip install python-virtualenv + + All files are installed under your virtualenv. + +Using the sources +----------------- + +#. Follow `get the sources `_ section to retrieve the sources. +#. Install from the source using:: + + python setup.py install + + +Using rpm package +----------------- + +There is currently no oficial packages for distributions. +However part of the sources there is a mechanism to buil rpm or deb packages for distributions. + +The mechanism is based on `project builder `_ tool. + +#. Follow `get the sources `_ section to retrieve the sources. +#. Download project builder for your distribution from ftp://ftp.project-builder.org. +#. Clone the project to your own github account. +#. Create a .pbrc with the following containt:: + + [uggla@ugglalaptop ~]$ cat .pbrc + pbdefdir python-redfish = $ENV{'HOME'}/workspace + pbconfdir python-redfish = $ENV{'HOME'}/workspace/python-redfish/pbconf + pbconfurl python-redfish = git+ssh://git@github.com:uggla/python-redfish.git + pburl python-redfish = git+ssh://git@github.com:uggla/python-redfish.git +#. Build the project:: + + pb -p python-redfish sbx2pkg + +#. All packages (srpm/rpm) should be available into the build directory, then install the package using rpm:: + + rpm -Uvh python-redfish/build/RPMS/python-redfish-devel20160213182552.rpm + + +#. Follow `get the sources `_ section to retrieve the sources. + +Using deb package +----------------- + +This installation in yet possible due to missing deb package dependencies. We are working on it. + +In the meantime we recommend to use `Using pip`_ or `Using pip and virtualenv`_. + +===================================== +Host configuration file configuration +===================================== + +#. Verify redfish-client is working correclty:: + + redfish-client.py -h + +#. Create a default entry to use the mockup:: + + redfish-client.py config add default default http://localhost:8000/redfish/v1 + +#. Verify the entry is correctly registered:: + + redfish-client.py config showall + +=================== +Mockup installation +=================== + +#. Follow `get the sources `_ section to retrieve the sources. +#. Install docker using your distribution packages or the docker `procedure `_ (docker provide more recent packages for ubuntu):: + + dnf install docker + systemctl enable docker.service + systemctl start docker.service + systemctl status docker.service + +#. Jump into the dmtf directory. +#. Run ./buildImage.sh and ./run-redfish-simulator.sh +#. Check that a container is running and listening on port 8000:: + + (pypi)[uggla@ugglalaptop dmtf]$ docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9943ff1d4d93 redfish-simulator:latest "/bin/sh -c /tmp/redf" 3 weeks ago Up 2 days 0.0.0.0:8000->80/tcp redfish-simulator +#. Try to connect using a navigator to http://localhost:8000 the following screen should apear. + + .. image:: images/simulator.jpg + +Note : in the above screenshot, firefox JSON-handle extension is used. If you want the same presentation install the extension and refresh the page. + +========================== +Testing against the mockup +========================== + +#. Follow `Host configuration file configuration`_ and `Mockup installation`_ section. +#. Run the following command:: + + redfish-client.py manager getinfo + +The result should be like this:: + + (pypi)[uggla@ugglalaptop dmtf]$ redfish-client.py manager getinfo + Gathering data from manager, please wait... + + Redfish API version : 1.00 + Root Service + + Managers information : + ====================== + + Manager id 1: + UUID : 00000000-0000-0000-0000-000000000000 + Type : BMC + Firmware version : 1.00 + State : Enabled + Ethernet Interface : + This manager has no ethernet interface + Managed Chassis : + 1 + Managed System : + 1 + ---------------------------- + + Manager id 2: + UUID : 00000000-0000-0000-0000-000000000000 + Type : EnclosureManager + Firmware version : Not available + State : Enabled + Ethernet Interface : + This manager has no ethernet interface + Managed Chassis : + Enc1 + Managed System : + 2 + ---------------------------- + + Manager id 3: + UUID : 00000000-0000-0000-0000-000000000000 + Type : EnclosureManager + Firmware version : Not available + State : Enabled + Ethernet Interface : + This manager has no ethernet interface + Managed Chassis : + Enc1 + Managed System : + 2 + ---------------------------- + + + +============================ +Building local documentation +============================ + +Building the html documentation locally + + +#. Follow `get the sources `_ section to retrieve the sources. +#. Jump in the doc directory:: + + cd doc +#. Build the html documentation:: + + make html + + +If you want to build the documentation in pdf. + +#. Get texlive full distribution, ex on Fedora:: + + dnf install texlive-scheme-full.noarch +#. Build the documentation:: + + make latexpdf - $ mkvirtualenv python-redfish - $ pip install python-redfish diff --git a/doc/source/usage.rst b/doc/source/usage.rst index e4b8cce..9661c40 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -2,6 +2,25 @@ Usage ======== -To use python-redfish in a project:: +Example using the mockup +------------------------ + +example/simple-simulator.py provide a simple library usage to interact with the +redfish mockup. + +Example using a proliant +------------------------ + +example/simple-proliant.py provide a simple library usage to interact with a HP +proliant BL460C G9 server. However this example should work on any server supplier following redfish +standard. + +refish-client usage +------------------- + +The clint usage can be display using:: + + redfish-client.py -h + +This is also available at http://pythonhosted.org/python-redfish/redfish-client.html . - import redfish diff --git a/examples/redfish.conf b/examples/redfish.conf index 80347c8..24cd951 100644 --- a/examples/redfish.conf +++ b/examples/redfish.conf @@ -1,5 +1,5 @@ { - "Nodes": { + "Managers": { "default": { "url": "", "login": "", diff --git a/examples/walk-chassis.py b/examples/walk-chassis.py deleted file mode 100644 index 22781ba..0000000 --- a/examples/walk-chassis.py +++ /dev/null @@ -1,58 +0,0 @@ -#!/usr/bin/env python - -#import logging -import sys -#from oslo_config import cfg -#from oslo_log import log as logging - -import redfish - -# Sets up basic logging for this module -#log_root = logging.getLogger('redfish') -#log_root.addHandler(logging.StreamHandler(sys.stdout)) -#log_root.setLevel(logging.DEBUG) - -#CONF = cfg.CONF -#logging.set_defaults(['redfish=DEBUG']) -#logging.register_options(CONF) -#logging.setup(CONF, "redfish") - -# Connect to a redfish API endpoint -host = 'http://localhost' -user_name = '' -password = '' - -# This returns a RedfishConnection object, which implements -# the low-level HTTP methods like GET, PUT, etc -connection = redfish.server.connect(host, user_name, password) - -# From this connection, we can get the Root resource. -# Note that the root resource is somewhat special - you create it from -# the connection, but you create other resources from the root resource. -# (You don't strictly have to do this, but it's simpler.) -root = connection.get_root() - -print("\n") -print("ROOT CONTROLLER") -print("===============") -print(root) - - -# The Root class has well-defined top-level resources, such as -# chassis, systems, managers, sessions, etc... -chassis = root.get_chassis() - -print("\n") -print("CHASSIS DATA") -print("============") -print(chassis) -print("\n") -print("WALKING CHASSIS") -print("\n") -print("CHASSIS contains %d items" % len(chassis)) -print("\n") -for item in chassis: - print("SYSTEM") - print("======") - print(item) - print("\n")