Commit 41e8cd1a authored by Marco Mariani's avatar Marco Mariani

documentiation cleanup

parent 50f2cfaf
......@@ -5,23 +5,21 @@ SlapOS command line usage
Notes:
------
* Default SlapOS Master is http://www.vifib.net. It can be changed by altering configuration files or with the `--master-url`
argument for commands that support it.
* Most commands (except node register) take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
* Default SlapOS Master is http://www.vifib.net. It can be changed by altering configuration files or with the ``--master-url``
argument for commands that support it.
If no such argument is provided:
* "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the path referenced by the
``SLAPOS_CONFIGURATION`` environment variable.
* Most commands take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
* likewise, "client" commands (request, supply...) use :file:`~/.slapos/slapos.cfg`, or the ``SLAPOS_CLIENT_CONFIGURATION`` variable.
If no such argument is provided:
* "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the file referenced by the
``SLAPOS_CONFIGURATION`` environment variable.
* likewise, "client" commands (request, supply...) use :file:`~/.slapos/slapos.cfg`, or the ``SLAPOS_CLIENT_CONFIGURATION`` variable.
XXX the SLAPOS_CONFIGURATION thing is repeated below for each command
we can remove it with :ellipsis:
XXX TODO document 'alias' for software_url, software_group?, computer_group?
......@@ -29,11 +27,15 @@ XXX TODO document 'alias' for software_url, software_group?, computer_group?
Common options
--------------
By itself, the ``slapos`` command lists all the available sub-commands and common options.
Without arguments, the ``slapos`` program lists all the available commands and common options.
.. program-output:: python slapos
The ``-q`` and ``-v`` options control the verbosity of console output (``-v``: DEBUG, default: INFO, ``-q``: WARNING).
Output to a logfile is not affected, and is the same as ``-v``.
SlapOS Client commands
......@@ -41,118 +43,115 @@ SlapOS Client commands
These commands are used by clients (as human beings or programs) to manage their own instances.
slapos request
~~~~~~~~~~~~~~
request
~~~~~~~
.. program-output:: python slapos help request
Examples
Request an instance and get status and parameters of instance.
Examples:
* Request a wordpress instance named "mybeautifulinstance" on Node named "COMP-12345"::
* Request a wordpress instance named "mybeautifulinstance" on Node named "COMP-12345"::
$ slapos request mybeautifulinstance wordpress --node id=COMP-12345
$ slapos request mybeautifulinstance wordpress --node id=COMP-12345
* Request a kvm instance named "mykvm" on Node named "COMP-12345", specifying nbd-host and nbd-ip parameters::
* Request a kvm instance named "mykvm" on Node named "COMP-12345", specifying nbd-host and nbd-ip parameters::
$ slapos request mykvm kvm --node id=COMP-12345 --configuration nbd-host=debian.nbd.vifib.org nbd-port=1024
$ slapos request mykvm kvm --node id=COMP-12345 --configuration \
nbd-host=debian.nbd.vifib.org nbd-port=1024
XXX Change in slaplib: allow to fetch instance params without changing anything. i.e we should do "slapos request myalreadyrequestedinstance" to fetch connection parameters without erasing previously defined instance parameters.
slapos search
~~~~~~~~~~~~~
Note: Not yet implemented.
Usage:
slapos search <search parameters ex. computer region, instance reference, source_section, etc.>
..
search
~~~~~~
Note: Not yet implemented.
Usage:
slapos search <search parameters ex. computer region, instance reference, source_section, etc.>
Returns visible instances matching search parameters.
Returns visible instances matching search parameters.
slapos supply
~~~~~~~~~~~~~
supply
~~~~~~
.. program-output:: python slapos help supply
Ask installation of a software on a specific node or group of nodes. Nodes will then be ready to accept instances of specified software.
Examples:
Examples
* Ask installation of wordpress Software Release on COMP-12345::
* Ask installation of wordpress Software Release on COMP-12345::
$ slapos supply wordpress COMP-12345
slapos remove
~~~~~~~~~~~~~
remove
~~~~~~
.. program-output:: python slapos help remove
Ask Removal of a software on a specific node or group of nodes. Existing instances won't work anymore.
Ask Removal of a software from a specific node or group of nodes. Existing instances won't work anymore.
XXX "slapos autounsupply a.k.a slapos cleanup"
Examples:
Examples
* Ask installation of wordpress Software Release on COMP-12345::
* Ask installation of wordpress Software Release on COMP-12345::
$ slapos supply wordpress COMP-12345
slapos autosupply
~~~~~~~~~~~~~~~~~
Note: Not yet implemented.
Usage:
slapos autosupply <software | software_group> <computer_guid | computer_group>
..
autosupply
~~~~~~~~~~
Note: Not yet implemented.
Usage:
slapos autosupply <software | software_group> <computer_guid | computer_group>
Like "slapos suppply", but on-demand. Software will be (re)installed only when at least one instance of this software is requested. When no instance of this software is deployed on the node, it will be uninstalled.
Like "slapos suppply", but on-demand. Software will be (re)installed only when at least one instance of this software is requested. When no instance of this software is deployed on the node, it will be uninstalled.
slapos console
~~~~~~~~~~~~~~
Enter in a python console with slap library imported.
console
~~~~~~~
.. program-output:: python slapos help console
slapos <stop|start|destroy>
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note: Not yet implemented.
Usage:
slapos <stop|start|destroy> <instance reference>
Ask start/stop/destruction of selected instance.
Example:
* Ask to stop "mywordpressinstance"::
$ slapos stop mywordpressinstance
..
<stop|start|destroy>
~~~~~~~~~~~~~~~~~~~~
Note: Not yet implemented.
Usage:
slapos <stop|start|destroy> <instance reference>
Ask start/stop/destruction of selected instance.
Example:
* Ask to stop "mywordpressinstance"::
$ slapos stop mywordpressinstance
SlapOS Node commands
--------------------
This kind of commands is used to control the current SlapOS Node. These commands are only useful for administrators of Nodes.
This group of commands is used to control the current SlapOS Node. They are only useful to Node administrators.
slapos node
~~~~~~~~~~~
node, node status
~~~~~~~~~~~~~~~~~
This is an alias for ``node supervisorctl status``.
These are aliases for ``node supervisorctl status``.
It displays the status of the node, also running the supervisor daemon if needed.
XXX Temporary note: equivalent of old slapgrid-supervisord + slapgrid-supervisorctl.
.. program-output:: python slapos help node supervisorctl status
.. program-output:: python slapos help node
slapos node register
~~~~~~~~~~~~~~~~~~~~
Usage:
******
node register
~~~~~~~~~~~~~
.. program-output:: python slapos help node register
......@@ -179,150 +178,176 @@ Parameters:
--partition-number NUMBER Number of partitions that will have your SlapOS Node. defaults to "10".
--ipv4-local-network NETWORK Subnetwork used to assign local IPv4 addresses. It should be a not used network in order to avoid conflicts. defaults to 10.0.0.0/16.
-t, --create-tap Will trigger creation of one virtual "tap" interface per Partition and attach it to primary interface. Requires primary interface to be a bridge. defaults to false. Needed to host virtual machines.
-n, --dry-run Don't touch to anything in the filesystem. Used to debug.
Notes:
******
* "IPv6 interface" and "create tap" won't be put at all in the SlapOS Node configuration file if not explicitly written.
Examples:
*********
* "IPv6 interface" and "create tap" won't be put at all in the SlapOS Node configuration file if not explicitly written.
* Register computer named "mycomputer" to vifib::
Examples
$ slapos node register mycomputer
* Register computer named "mycomputer" to vifib::
* Register computer named "mycomputer" to vifib using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet::
$ slapos node register mycomputer
$ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
--ipv4-local-network 11.0.0.0/16
* Register computer named "mycomputer" to vifib using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet::
* Register computer named "mycomputer" to another SlapOS master accessible via https://www.myownslaposmaster.com, and SLAP webservice accessible via https://slap.myownslaposmaster.com (Note that this address should be the "slap" webservice URL, not web URL)::
$ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
--ipv4-local-network 11.0.0.0/16
$ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
--master-url-web https://www.myownslaposmaster.com
* Register computer named "mycomputer" to another SlapOS master accessible via https://www.myownslaposmaster.com, and SLAP webservice accessible via https://slap.myownslaposmaster.com (Note that this address should be the "slap" webservice URL, not web URL)::
$ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
--master-url-web https://www.myownslaposmaster.com
XXX-Cedric : To be implemented
* Register computer named "mycomputer" to vifib, and ask to create tap interface to be able to host KVMs::
$ slapos node register mycomputer --create-tap
* Register computer named "mycomputer" to vifib, and ask to create tap interface to be able to host KVMs::
$ slapos node register mycomputer --create-tap
slapos node software
~~~~~~~~~~~~~~~~~~~~
Usage:
******
.. program-output:: python slapos help node software
node software
~~~~~~~~~~~~~
Run software installation/deletion.
.. program-output:: python slapos help node software
Temporary note: equivalent of old slapgrid-sr.
# XXX: only_sr should be named ??? (process-only ?)
# XXX: add a "-vv", very verbose, option.
Parameters:
***********
--logfile LOGFILE If specified, will log as well output in the file located at FILE.
--only_sr URL Only process one specific Software Release that has been supplied on this Computer. If not supplied: do nothing.
--all Process all Software Releases, even already installed.
--verbose, -v Be more verbose.
Return values:
**************
(Among other standard Python return values)
0 Everything went fine
1 At least one software hasn't correctly been installed.
* 0 Everything went fine
* 1 At least one software hasn't correctly been installed.
slapos node instance
~~~~~~~~~~~~~~~~~~~~
Usage:
******
.. program-output:: python slapos help node instance
node instance
~~~~~~~~~~~~~
Temporary note: equivalent of old slapgrid-cp.
.. program-output:: python slapos help node instance
Run instances deployment.
Parameters:
***********
--logfile LOGFILE If specified, will log as well output in the file located at FILE.
--only_cp PARTITION Only process one specific Computer Partition, if possible.
--all Force processing all Computer Partitions.
--verbose, -v Be more verbose.
Return values:
**************
(Among other standard Python return values)
0 Everything went fine
1 At least one instance hasn't correctly been processed.
2 At least one promise has failed.
* 0 Everything went fine
* 1 At least one instance hasn't correctly been processed.
* 2 At least one promise has failed.
slapos node report
~~~~~~~~~~~~~~~~~~
Usage:
******
::
node report
~~~~~~~~~~~
.. program-output:: python slapos help node report
Run instance reports and garbage collection.
Temporary note: equivalent of old slapgrid-ur.
Parameters:
***********
--logfile LOGFILE If specified, will log as well output in the file located at FILE.
--verbose, -v Be more verbose.
Return values:
**************
(Among other standard Python return values)
0 Everything went fine
1 At least one instance hasn't correctly been processed.
* 0 Everything went fine
* 1 At least one instance hasn't correctly been processed.
slapos node <start|stop|restart|tail|status>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usage:
slapos node <start|stop|restart|tail|status> <instance>:[process]
Start/Stop/Restart/Show stdout/stderr of instance and/or process.
node start|stop|restart|tail|status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Examples:
usage: slapos node <start|stop|restart|tail|status> [-h] [--cfg CFG] <instance>:[process]
* Start all processes of slappart3:
slapos node start slappart3:
Start/Stop/Restart/Show stdout/stderr of instance and/or process.
* Stop only apache in slappart1:
slapos node stop slappart1:apache
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file - defaults to
$SLAPOS_CONFIGURATION or /etc/opt/slapos/slapos.cfg
* Show stdout/stderr of mysqld in slappart2:
slapos node tail slappart2:mysqld
Examples
slapos node supervisorctl
~~~~~~~~~~~~~~~~~~~~~~~~~
* Start all processes of slappart3::
$ slapos node start slappart3:
* Stop only apache in slappart1::
$ slapos node stop slappart1:apache
* Show stdout/stderr of mysqld in slappart2::
$ slapos node tail slappart2:mysqld
node supervisorctl
~~~~~~~~~~~~~~~~~~
.. program-output:: python slapos help node supervisorctl
Enter into supervisor console.
slapos node supervisord
~~~~~~~~~~~~~~~~~~~~~~~
node supervisord
~~~~~~~~~~~~~~~~
.. program-output:: python slapos help node supervisord
Launch, if not already launched, supervisor daemon.
slapos node log
~~~~~~~~~~~~~~~
Note: Not yet implemented.
Usage:
slapos node log <software|instance|report>
Display log.
..
node log
~~~~~~~~
Note: Not yet implemented.
Usage:
slapos node log <software|instance|report>
Display log.
SlapOS Miscellaneous commands
-----------------------------
cache lookup
~~~~~~~~~~~~
.. program-output:: python slapos help cache lookup
Examples
* See if the wordpress Software Release is available in precompiled format for our distribution::
$ slapos cache lookup http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/tags/slapos-0.156:/software/kvm/software.cfg
Software URL: http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/tags/slapos-0.156:/software/kvm/software.cfg
MD5: 4410088e11f370503e9d78db4cfa4ec4
-------------
Available for:
distribution | version | id | compatible?
-----------------+--------------+----------------+-------------
CentOS | 6.3 | Final | no
Fedora | 17 | Beefy Miracle | no
Ubuntu | 12.04 | precise | yes
debian | 6.0.6 | | no
debian | 7.0 | | no
......@@ -8,7 +8,7 @@ from slapos.client import init, do_console, ClientConfig
class ConsoleCommand(ClientConfigCommand):
"""
python prompt to interact with slap API
python console with slap library imported
You can play with the global "slap" object and
with the global "request" method.
......
......@@ -21,9 +21,7 @@ def parse_option_dict(options):
class RequestCommand(ClientConfigCommand):
"""
request an Instance
"""
"""request an instance and get status and parameters of instance"""
log = logging.getLogger('request')
......
......@@ -55,9 +55,6 @@ class SlapgridCommand(ConfigCommand):
help='Promise timeout in seconds.')
ap.add_argument('--now', action='store_true',
help='Launch slapgrid without delay. Default behavior.')
ap.add_argument('--all', action='store_true',
help='Launch slapgrid to process all Softare Releases '
'and/or Computer Partitions.')
return ap
def take_action(self, args):
......@@ -83,7 +80,7 @@ class SlapgridCommand(ConfigCommand):
class SoftwareCommand(SlapgridCommand):
"""hook for entry point to process Software Releases"""
"""run software installation/deletion"""
log = logging.getLogger('software')
......@@ -92,6 +89,8 @@ class SoftwareCommand(SlapgridCommand):
def get_parser(self, prog_name):
ap = super(SoftwareCommand, self).get_parser(prog_name)
ap.add_argument('--all', action='store_true',
help='Launch slapgrid to process all Softare Releases.')
ap.add_argument('--only-sr', '--only',
help='Force the update of a single software release (can be full URL or MD5 hash), '
'even if is already installed. This option will make all other '
......@@ -100,7 +99,7 @@ class SoftwareCommand(SlapgridCommand):
class InstanceCommand(SlapgridCommand):
"""hook for entry point to process Computer Partitions"""
"""run instance deployment"""
log = logging.getLogger('instance')
......@@ -109,6 +108,8 @@ class InstanceCommand(SlapgridCommand):
def get_parser(self, prog_name):
ap = super(InstanceCommand, self).get_parser(prog_name)
ap.add_argument('--all', action='store_true',
help='Launch slapgrid to process all Computer Partitions.')
ap.add_argument('--only-cp', '--only',
help='Update a single or a list of computer partitions '
'(ie.:slappartX, slappartY), '
......@@ -117,7 +118,7 @@ class InstanceCommand(SlapgridCommand):
class ReportCommand(SlapgridCommand):
"""hook for entry point to process Usage Reports"""
"""run instance reports and garbage collection"""
log = logging.getLogger('report')
......
......@@ -11,9 +11,7 @@ import supervisor.supervisorctl
class SupervisorctlCommand(ConfigCommand):
"""
manage supervisor processes
"""
"""enter into supervisor console, for process management"""
log = logging.getLogger('supervisorctl')
......
......@@ -8,7 +8,7 @@ from slapos.grid.svcbackend import launchSupervisord
class SupervisordCommand(ConfigCommand):
"""run the supervisor daemon"""
"""launch, if not already running, supervisor daemon"""
log = logging.getLogger('supervisord')
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment