xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-06-18 04:10:46 +00:00
Code Issues Releases Wiki Activity

Made changes for syntax errors in restapi doc

Browse Source
This commit is contained in:
wangxiaopeng
2016-01-10 22:00:27 -05:00
parent af02dbd3ba
commit 4ab5232e47
2 changed files with 20 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/source/advanced/restapi/restapi_setup/restapi_setup.rst
View File

@ -1,7 +1,7 @@
Enable the HTTPS service for REST API
=====================================
To improve the security between the REST API client and server, enabling the HTTPS service on the xCAT management is recommended. And the REST API client should use the 'https' to access web server instead of the 'http'.
To improve the security between the REST API client and server, enabling the HTTPS service on the xCAT MN is recommended. And the REST API client should use the 'https' to access web server instead of the 'http'.
* **[RHEL6 (x86_64/ppc64) and RHEL5 (x86_64)]** ::
@ -50,7 +50,7 @@ To change the hostname, edit /etc/sysconfig/network (RHEL) or /etc/HOSTNAME (SLE
hostname <newFQDN>
After change the hostname, run the xcat command ``xcatconfig`` to generate a new server certificate base on the correct hostname: ::
After changing the hostname, run the xcat command ``xcatconfig`` to generate a new server certificate based on the correct hostname: ::
xcatconfig -c
@ -92,19 +92,20 @@ Some operations like 'create osimage' (copycds) need a long time (longer than 3
Set Up an Account for Web Service Access
========================================
User needs a username and password to access the REST API. When the REST API request is passed to xcatd, the username and password will be verified base on the :doc:`xCAT passwd Table </guides/admin-guides/references/man5/passwd.5>`, and then xcatd will look in the `xCAT policy Table </guides/admin-guides/references/man5/policy.5>` to see if the user is allowed to perform the requested operation.
User needs a username and password to access the REST API. When the REST API request is passed to xcatd, the username and password will be verified based on the :doc:`xCAT passwd Table </guides/admin-guides/references/man5/passwd.5>`, and then xcatd will look in the :doc:`xCAT policy Table </guides/admin-guides/references/man5/policy.5>` to see if the user is allowed to perform the requested operation.
The account which key is **xcat** will be used for the REST API authentication. The username and password should be passed in as the attirbutes of URL:
userName: Pass the username of the account
userPW: Pass the password of the account (xCAT 2.10)
password: Pass the password of the account (xCAT earlier than 2.10)
The account with key of **xcat** will be used for the REST API authentication. The username and password should be passed in as the attirbutes of URL:
* userName: Pass the username of the account
* userPW: Pass the password of the account (xCAT 2.10)
* password: Pass the password of the account (xCAT earlier than 2.10)
You can use the root userid for your API calls, but we recommend you create a new userid (for example wsuser) for the API calls and give it the specific privileges you want it to have.
Use root Account
----------------
The certificate and ssh keys for **root** account has been created during the install of xCAT. The public ssh key also has been uploaded to computer node so that xCAT MN can ssh to CN without password. Then the only thing needs to do is to add the password for the **root** in the passwd table. ::
The certificate and ssh keys for **root** account has been created during the install of xCAT. The public ssh key also has been uploaded to compute node so that xCAT MN can ssh to CN without password. Then the only thing left to do is to add the password for the **root** in the passwd table. ::
tabch key=xcat,username=root passwd.password=<root-pw>
@ -126,7 +127,7 @@ Create the SSL certificate under that user's home directory so that user can be
When running this command you'll see SSL certificates created. Enter "y" where prompted and take the defaults.
To enable the POST method of resources like nodeshell,nodecopy,updating,filesyncing for the non-root user, you need to enable the ssh communication between xCAT MN and CN without password. Log in as <username> and run following command: ::
To enable the POST method of resources like nodeshell, nodecopy, updating and filesyncing for the non-root user, you need to enable the ssh communication between xCAT MN and CN without password. Log in as <username> and run following command: ::
xdsh <noderange> -K

20
docs/source/advanced/restapi/restapi_usage/restapi_usage.rst
View File

@ -22,7 +22,7 @@ xCAT REST API supports two ways to authenticate the access user: user account (u
User Account
------------
Follow the steps in `WEB Service Setup </advanced/restapi/restapi_setup/index>`, you have created an account for yourself. Use this pair of username and password, you can access the https server.
Follow the steps in :doc:`WEB Service Setup </advanced/restapi/restapi_setup/index>`, you can create an account for yourself. Then use that username and password to access the https server.
The general format of the URL used in the REST API call is: ::
@ -42,7 +42,7 @@ Example: ::
Access Token
------------
xCAT also supports to use the Access Token to replace the using of username+password in every access. Before the access to any resource, you need get a token first with your account (username+password) ::
xCAT also supports the use the Access Token to replace the using of username+password in every access. Before accessing any resource, you need get a token with your account (username+password) ::
# curl -X POST --cacert /root/ca-cert.pem \
'https://<FQDN of xCAT MN>/xcatws/tokens?pretty=1' -H Content-Type:application/json --data \
@ -58,13 +58,13 @@ Then in the subsequent REST API access, the token can be used to replace the use
curl -X GET --cacert /root/ca-cert.pem -H X-Auth-Token:5cabd675-bc2e-4318-b1d6-831fd1f32f97 'https://<FQDN of xCAT MN>/xcatws/<resource>?<parameters>
The validity of token of 24 hours. If an used token has been expired, you will get a 'Authentication failure' error. Then you need reacquire a token with your account.
The validity of token is 24 hours. If an old token has expired, you will get a 'Authentication failure' error. Then you need reacquire a token with your account.
The Common Parameters for Resource URI
======================================
xCAT REST API supports to use several common parameters in the resource URI to enable specific output:
xCAT REST API supports several common parameters in the resource URI to enable specific output:
* **pretty=1** \- It is used to format the json output for easier viewing on the screen. ::
@ -86,7 +86,7 @@ xCAT REST API supports to use several common parameters in the resource URI to e
}
}
``Note:`` All the above parameters can be used in mixed like following: ::
``Note:`` All the above parameters can be used together like following: ::
https://<xCAT MN>/xcatws/nodes?pretty=1&debug=1
@ -101,7 +101,7 @@ When an Error occurs during the operation
(i.e. there's error/errorcode in the output of xcat xml response):
When error happens, for all the GET/PUT/POST/DELETE methods, the output will only includes 'error' and 'errorcode' properties: ::
When error happens, for all the GET/PUT/POST/DELETE methods, the output will only include 'error' and 'errorcode' properties: ::
{
error:[
@ -170,12 +170,12 @@ If the output is not object related, put all the output in a list (array): ::
For the PUT/DELETE methods
``````````````````````````
There will be no output for operations that succeed. (We made this decision because the output for them is always not formatted, and no program will read it if xcat indicates the operation has succeeded.)
There will be no output for operations that succeeded. (We made this decision because the output for them not formatted, and no program will read it if xcat indicates the operation has succeeded.)
For POST methods
````````````````
Since POST methods can either be creates or general actions, there is not as much consistency. In the case of a create, the rule is the same as PUT/DELETE (no output if successful). For actions that have output that matters (e.g. nodeshell, filesyncing, sw, postscript), the rules are like the GET method.
Since POST methods can either be creates or general actions, there is not much consistency. In the case of a create, the rule is the same as PUT/DELETE (no output if successful). For actions that have output that matters (e.g. nodeshell, filesyncing, sw, postscript), the rules are like the GET method.
Testing the API
@ -193,7 +193,7 @@ Refer to the file /opt/xcat/ws/xcatws-test.pl: ::
An Example Script of How to Use curl to Test Your xCAT REST API Service
-----------------------------------------------------------------------
It can be used as an initial script to make your xCAT REST API script to access and control xCAT resources. From the output message, you also could get the idea of how to access xCAT resources. ::
It can be used as an example script to access and control xCAT resources. From the output message, you also could get the idea of how to access xCAT resources. ::
/opt/xcat/ws/xcatws-test.sh
./xcatws-test.sh -u root -p cluster
@ -204,7 +204,7 @@ It can be used as an initial script to make your xCAT REST API script to access
But for exploration and experimentation, you can make API calls from your browser or using the **curl** command.
To make an API call from your browser, use the desired URL from this document. To simplify the test step, all the examples for the resources uses 'curl -k' to use insecure http connection and use the 'username+password' to authenticate the user. ::
To make an API call from your browser, uses the desired URL from this document. To simplify the test step, all the examples for the resources uses 'curl -k' to use insecure http connection and use the 'username+password' to authenticate the user. ::
curl -X GET -k 'https://myserver/xcatws/nodes?userName=xxx&userPW=xxx&pretty=1'