..  _`cmd`:

##################
Command-Line Use
##################

The :mod:`pyvix2.cli` module is the comman line API for PyVix2.
It allows a number of operations on local or remote hosts.

..  parsed-literal::

    python -m pyvix2.cli
    
This is not a complete implementation of the various features
of VIX.  It's an implementation that allows an administrator
some of the more common VIX operations.

Further, it can easily be extended to modify the implementation
or add features.

Concepts
============

There are several layers of context which are maintained
by VMware and PyVIX2.cli.

1.  The host.  Hosts are named via the configuration file.
    The ``default_host`` parameter defines the host chosen
    when the program starts.

2.  A current VM on the host.  The prompt changes to show
    which VM is current.  VM's are named via the configuration
    file.

3.  A current logged-in user on the VM on the host.

4.  A current snapshot for the VM on the host.

There are several commands for interacting with VMware services, 
and VM's.

..  parsed-literal::

    vm< help

    Documented commands (type help <topic>):
    ========================================
    EOF   bye    get      host  login   ls   python  remsnap  running   start  vm
    bash  check  getsnap  list  logout  put  quit    revert   snapshot  stop

    Other Commands
    ==============
    help
    
Host Connection
================

There are two host commands: `host [name]`_ and `list`_.

``host [name]``
-------------------

This will connect with a given VMware service provider.
This also sets the host context.  The context is changed by exiting
the progam or issuing another `host` command.

The host connection parameters are fetched from the configuration
file.  Each connection has a name and a dictionary of additional
parameters.  This dictionary becomes keyword parameters for the
:meth:`pyvix2.Host.connect` method.

If no name is provided, then the configuration named by the 
``default_host`` parameter is used.

``list``
-----------

Once connected, this will list VM's running under control of the 
current host.

VM Selection
=================

The `vm [name]`_, `start [name]`_, and `stop [name]`_ commands all make a named VM
the current working VM.  The ``start`` command also does power on.
The ``stop`` command also does power off.

The host VM filenames are fetched from the configuration
file.  Each VM has an alias and a local filename.

If the name is omitted, then the list of names from the
configuration file are shown.

``vm [name]``
--------------

Opens the VM.  If it's running, checks for tools.

..  parsed-literal:;

    vm< vm
        Available VMX
        SUSE: G:\VMplanet-openSUSE11.3\[VMplanet] openSUSE 11.3.vmx
        Fedora: C:\Fedora14\Fedora.vmx
    vm< vm SUSE
    Host openVM 0
    The virtual machine needs to be powered on
    Traceback (most recent call last):
      File "cmd.py", line 109, in do_vm
        self.current_vm.wait_for_tools_in_guest(10)
    Error: The virtual machine needs to be powered on
    SUSE<

The ``vm<`` prompt indicates no specific VM has been selected.

The ``SUSE<`` prompt shows that the current VM is now the one
identified by ``SUSE`` in the configuration. 

``start [name]``
----------------

Opens the VM, powers it on, and checks for tools.  Since VM's take time
to start, this will wait as long as 120 seconds to determine of tools
are present.

..  parsed-literal:;

    SUSE< start SUSE
    Host openVM 0
    VM power_on 0
    Check for tools...VM wait_for_tools_in_guest 0
    VIX_PROPERTY_VM_TOOLS_STATE: running

``stop [name]``
-----------------

Opens the VM, powers it off.  If tools are present, does a power
off from within the VM.  If tools are absent, simply powers it off.

VM Processes
=================

In order to access VM resources, it's essential that (1) the VM be powered on,
(2) the VM have tools installed, and (3) the user has credentials on the VM.
The `login [name]`_ and `logout`_ command will login to the VM.

Once logged in, then the commands `running`_, `check word...`_, `python script` and
`bash command` can be used.

``login [name]``
------------------

This will login to the VM.  The user remains logged in until (1) another login,
(2) logout or (3) the VM is powered off.

..  parsed-literal::

    SUSE< login slott
    password:
    VM login 0
    SUSE<

``logout``
-----------

Logout from the VM.

``running``
-------------

This is a list of processes running on the VM.

..  parsed-literal::

    SUSE< running
    VM wait_for_tools_in_guest 0
    VIX_PROPERTY_VM_TOOLS_STATE: running
    VM process_list 0
    Processes: 91
    1 root Tue Oct 04 11:36:40 2011 init [5]
    2 root Tue Oct 04 11:36:40 2011 kthreadd
    3 root Tue Oct 04 11:36:40 2011 migration/0
    4 root Tue Oct 04 11:36:40 2011 ksoftirqd/0
    
    **etc.**

``check word``...
--------------------

This will check the list of processes for any of the supplied words.
If a process has a name with a given word, that's shown.

..  parsed-literal::

    SUSE< check mysql
    VM wait_for_tools_in_guest 0
    VIX_PROPERTY_VM_TOOLS_STATE: running
    VM process_list 0
    Processes: 91
    Looking for ['mysql']
    3891 root Tue Oct 04 11:38:12 2011 /bin/sh /usr/bin/mysqld_safe --mysqld=mysqld
    --user=mysql --pid-file=/var/run/mysql/mysqld.pid --socket=/var/run/mysql/mysql.
    sock --datadir=/var/lib/mysql
    4122 mysql Tue Oct 04 11:38:12 2011 /usr/sbin/mysqld --basedir=/usr --datadir=/v
    ar/lib/mysql --user=mysql --log-error=/var/log/mysql/mysqld.log --pid-file=/var/
    run/mysql/mysqld.pid --socket=/var/run/mysql/mysql.sock --port=3306
    SUSE<

Two processes were found with `mysql` in their name: 3891 and 4122.

``bash command``
-------------------

The one-line ``bash`` command is executed.

..  parsed-literal::

    bash date >/home/slott/timestamp

This command doesn't produce any output.  To see if a command was started
properly, use `running`_ or `check word...`_.  Or, be sure that the ``bash``
command creates an output file, and get that file.

``python script``
-------------------

The given Python script file is executed.  Note that the filename must
(generally) be fully qualified.

..  parsed-literal::

    python /path/to/script.py

This command doesn't produce any output.  Be sure that the Python
script creates an output file, and get that file.

VM Files and Directories
===========================

In order to access VM resources, it's essential that (1) the VM be powered on,
(2) the VM have tools installed, and (3) the user has credentials on the VM.
The `login [name]`_ and `logout`_ command will login to the VM.

``get <guest> <host>``
---------------------------

Copy a file from the guest to the host.

..  parsed-literal::

    SUSE< bash date >/home/slott/timestamp
    VM script_run 0
    SUSE< get /home/slott/timestamp here
    VM file_copy_from_guest 0
    here
    >>> Tue Oct  4 11:02:04 CDT 2011

The `>>>` line shows the content of the file fetched from the VM.

``put <host> <guest>``
---------------------------

Copy a file from the host to the guest.

``ls <guest>``
-----------------------------

Get a directory listing of files on the guest OS.  The path should be fully
specified.

..  parsed-literal::

    SUSE< ls /home/slott
    VM directory_list 0
    Files: 57
    d Templates Fri Feb 25 08:47:33 2011
      timestamp Tue Oct 04 11:46:15 2011
      hello.py Wed Sep 28 16:37:04 2011
    d Public Fri Feb 25 08:47:33 2011
    d Pictures Fri Feb 25 08:47:33 2011
    d public_html Fri Feb 25 08:37:09 2011
    d Desktop Fri Feb 25 08:48:01 2011
    d bin Fri Feb 25 08:37:09 2011
      status Wed Sep 28 16:39:14 2011
    d Documents Sun Oct 02 11:30:01 2011
    d Music Fri Feb 25 08:47:33 2011
      hostfile Sun Oct 02 16:04:27 2011
    d Videos Fri Feb 25 08:47:33 2011
    d Downloads Wed Jun 22 11:56:01 2011

Snapshots
=================

See the VMware and VIX documentation for details on snapshots and
how they work.

``snapshot name description``
----------------------------------

Creates a snapshot.  This also becomes the "current" snapshot for
further operations.

``getsnap [name]``
-----------------------------------

Locate the named snapshot.  This becomes the current snapshot.

If a name is provided, the snapshot is found by name.

If a name is not provided, the existing current snapshot is found.

``remsnap``
------------------------------------

Remove the current snapshot.

``revert``
------------------------------------

Revert the VM to the given snapshot.