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

documentiation cleanup

parent 50f2cfaf
...@@ -5,23 +5,21 @@ SlapOS command line usage ...@@ -5,23 +5,21 @@ SlapOS command line usage
Notes: Notes:
------ ------
* Default SlapOS Master is http://www.vifib.net. It can be changed by altering configuration files or with the `--master-url`
* 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. argument for commands that support it.
* Most commands (except node register) take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``. * Most commands take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
If no such argument is provided: If no such argument is provided:
* "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the path referenced by the * "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the file referenced by the
``SLAPOS_CONFIGURATION`` environment variable. ``SLAPOS_CONFIGURATION`` environment variable.
* likewise, "client" commands (request, supply...) use :file:`~/.slapos/slapos.cfg`, or the ``SLAPOS_CLIENT_CONFIGURATION`` 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? 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? ...@@ -29,11 +27,15 @@ XXX TODO document 'alias' for software_url, software_group?, computer_group?
Common options 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 .. 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 SlapOS Client commands
...@@ -41,91 +43,92 @@ SlapOS Client commands ...@@ -41,91 +43,92 @@ SlapOS Client commands
These commands are used by clients (as human beings or programs) to manage their own instances. 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 .. program-output:: python slapos help request
Examples
Request an instance and get status and parameters of instance. * Request a wordpress instance named "mybeautifulinstance" on Node named "COMP-12345"::
Examples:
* 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. 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 ..
~~~~~~~~~~~~~ search
Note: Not yet implemented. ~~~~~~
Usage: Note: Not yet implemented.
Usage:
slapos search <search parameters ex. computer region, instance reference, source_section, etc.> 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 .. 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. 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 supply wordpress COMP-12345
slapos remove remove
~~~~~~~~~~~~~ ~~~~~~
.. program-output:: python slapos help 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" 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 supply wordpress COMP-12345
slapos autosupply ..
~~~~~~~~~~~~~~~~~ autosupply
Note: Not yet implemented. ~~~~~~~~~~
Usage: Note: Not yet implemented.
Usage:
slapos autosupply <software | software_group> <computer_guid | computer_group> 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 console
~~~~~~~~~~~~~~ ~~~~~~~
Enter in a python console with slap library imported.
.. program-output:: python slapos help console .. program-output:: python slapos help console
slapos <stop|start|destroy> ..
~~~~~~~~~~~~~~~~~~~~~~~~~~~ <stop|start|destroy>
Note: Not yet implemented. ~~~~~~~~~~~~~~~~~~~~
Usage: Note: Not yet implemented.
Usage:
slapos <stop|start|destroy> <instance reference> slapos <stop|start|destroy> <instance reference>
Ask start/stop/destruction of selected instance. Ask start/stop/destruction of selected instance.
Example: Example:
* Ask to stop "mywordpressinstance":: * Ask to stop "mywordpressinstance"::
...@@ -136,23 +139,19 @@ Example: ...@@ -136,23 +139,19 @@ Example:
SlapOS Node commands 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. 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 node register
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Usage:
******
.. program-output:: python slapos help node register .. program-output:: python slapos help node register
...@@ -179,150 +178,176 @@ Parameters: ...@@ -179,150 +178,176 @@ Parameters:
--partition-number NUMBER Number of partitions that will have your SlapOS Node. defaults to "10". --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. --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. -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: 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
* Register computer named "mycomputer" to vifib::
$ slapos node register mycomputer $ slapos node register mycomputer
* 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 vifib using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet::
$ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \ $ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
--ipv4-local-network 11.0.0.0/16 --ipv4-local-network 11.0.0.0/16
* 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):: * 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 \ $ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
--master-url-web https://www.myownslaposmaster.com --master-url-web https://www.myownslaposmaster.com
XXX-Cedric : To be implemented XXX-Cedric : To be implemented
* Register computer named "mycomputer" to vifib, and ask to create tap interface to be able to host KVMs::
* 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 register mycomputer --create-tap
slapos node software node software
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Usage:
******
.. program-output:: python slapos help node software .. program-output:: python slapos help node software
Run software installation/deletion.
Temporary note: equivalent of old slapgrid-sr.
# XXX: only_sr should be named ??? (process-only ?)
# XXX: add a "-vv", very verbose, option.
Parameters: 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. --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. --all Process all Software Releases, even already installed.
--verbose, -v Be more verbose.
Return values: Return values:
************** **************
(Among other standard Python 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: 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. --only_cp PARTITION Only process one specific Computer Partition, if possible.
--all Force processing all Computer Partitions. --all Force processing all Computer Partitions.
--verbose, -v Be more verbose.
Return values: Return values:
************** **************
(Among other standard Python 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
~~~~~~~~~~~~~~~~~~ node report
Usage: ~~~~~~~~~~~
******
::
.. program-output:: python slapos help node report .. program-output:: python slapos help node report
Run instance reports and garbage collection. 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: Return values:
************** **************
(Among other standard Python 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.
node start|stop|restart|tail|status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
usage: slapos node <start|stop|restart|tail|status> [-h] [--cfg CFG] <instance>:[process]
Start/Stop/Restart/Show stdout/stderr of instance and/or process.
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
slapos node <start|stop|restart|tail|status> Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usage:
slapos node <start|stop|restart|tail|status> <instance>:[process]
Start/Stop/Restart/Show stdout/stderr of instance and/or process. * Start all processes of slappart3::
Examples: $ slapos node start slappart3:
* Start all processes of slappart3: * Stop only apache in slappart1::
slapos node start slappart3:
* Stop only apache in slappart1: $ slapos node stop slappart1:apache
slapos node stop slappart1:apache
* Show stdout/stderr of mysqld in slappart2: * Show stdout/stderr of mysqld in slappart2::
slapos node tail slappart2:mysqld
slapos node supervisorctl $ slapos node tail slappart2:mysqld
~~~~~~~~~~~~~~~~~~~~~~~~~
node supervisorctl
~~~~~~~~~~~~~~~~~~
.. program-output:: python slapos help 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 .. program-output:: python slapos help node supervisord
Launch, if not already launched, supervisor daemon.
slapos node log
~~~~~~~~~~~~~~~ ..
Note: Not yet implemented. node log
Usage: ~~~~~~~~
Note: Not yet implemented.
Usage:
slapos node log <software|instance|report> slapos node log <software|instance|report>
Display log. 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 ...@@ -8,7 +8,7 @@ from slapos.client import init, do_console, ClientConfig
class ConsoleCommand(ClientConfigCommand): 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 You can play with the global "slap" object and
with the global "request" method. with the global "request" method.
......
...@@ -21,9 +21,7 @@ def parse_option_dict(options): ...@@ -21,9 +21,7 @@ def parse_option_dict(options):
class RequestCommand(ClientConfigCommand): class RequestCommand(ClientConfigCommand):
""" """request an instance and get status and parameters of instance"""
request an Instance
"""
log = logging.getLogger('request') log = logging.getLogger('request')
......
...@@ -55,9 +55,6 @@ class SlapgridCommand(ConfigCommand): ...@@ -55,9 +55,6 @@ class SlapgridCommand(ConfigCommand):
help='Promise timeout in seconds.') help='Promise timeout in seconds.')
ap.add_argument('--now', action='store_true', ap.add_argument('--now', action='store_true',
help='Launch slapgrid without delay. Default behavior.') 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 return ap
def take_action(self, args): def take_action(self, args):
...@@ -83,7 +80,7 @@ class SlapgridCommand(ConfigCommand): ...@@ -83,7 +80,7 @@ class SlapgridCommand(ConfigCommand):
class SoftwareCommand(SlapgridCommand): class SoftwareCommand(SlapgridCommand):
"""hook for entry point to process Software Releases""" """run software installation/deletion"""
log = logging.getLogger('software') log = logging.getLogger('software')
...@@ -92,6 +89,8 @@ class SoftwareCommand(SlapgridCommand): ...@@ -92,6 +89,8 @@ class SoftwareCommand(SlapgridCommand):
def get_parser(self, prog_name): def get_parser(self, prog_name):
ap = super(SoftwareCommand, self).get_parser(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', ap.add_argument('--only-sr', '--only',
help='Force the update of a single software release (can be full URL or MD5 hash), ' 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 ' 'even if is already installed. This option will make all other '
...@@ -100,7 +99,7 @@ class SoftwareCommand(SlapgridCommand): ...@@ -100,7 +99,7 @@ class SoftwareCommand(SlapgridCommand):
class InstanceCommand(SlapgridCommand): class InstanceCommand(SlapgridCommand):
"""hook for entry point to process Computer Partitions""" """run instance deployment"""
log = logging.getLogger('instance') log = logging.getLogger('instance')
...@@ -109,6 +108,8 @@ class InstanceCommand(SlapgridCommand): ...@@ -109,6 +108,8 @@ class InstanceCommand(SlapgridCommand):
def get_parser(self, prog_name): def get_parser(self, prog_name):
ap = super(InstanceCommand, self).get_parser(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', ap.add_argument('--only-cp', '--only',
help='Update a single or a list of computer partitions ' help='Update a single or a list of computer partitions '
'(ie.:slappartX, slappartY), ' '(ie.:slappartX, slappartY), '
...@@ -117,7 +118,7 @@ class InstanceCommand(SlapgridCommand): ...@@ -117,7 +118,7 @@ class InstanceCommand(SlapgridCommand):
class ReportCommand(SlapgridCommand): class ReportCommand(SlapgridCommand):
"""hook for entry point to process Usage Reports""" """run instance reports and garbage collection"""
log = logging.getLogger('report') log = logging.getLogger('report')
......
...@@ -11,9 +11,7 @@ import supervisor.supervisorctl ...@@ -11,9 +11,7 @@ import supervisor.supervisorctl
class SupervisorctlCommand(ConfigCommand): class SupervisorctlCommand(ConfigCommand):
""" """enter into supervisor console, for process management"""
manage supervisor processes
"""
log = logging.getLogger('supervisorctl') log = logging.getLogger('supervisorctl')
......
...@@ -8,7 +8,7 @@ from slapos.grid.svcbackend import launchSupervisord ...@@ -8,7 +8,7 @@ from slapos.grid.svcbackend import launchSupervisord
class SupervisordCommand(ConfigCommand): class SupervisordCommand(ConfigCommand):
"""run the supervisor daemon""" """launch, if not already running, supervisor daemon"""
log = logging.getLogger('supervisord') 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