# Command Line Tool - mod_python

## Overview of mod_python command

mod_python includes a command-line tool named `mod_python`. The `mod_python` command exists to facilitate tasks related to configuration and management of mod_python.

The general syntax for the command is `mod_python <subcommand> <arguments>` where `<subcommand>` is a separate tool with its own argument requirements.

## mod_python command line tool sub-commands

### create

`create` sub-command creates a simple Apache configuration and a skeleton directory structure necessary for placement of configuration, logs and content. It is meant to be executed only once per lifetime of a project.

The configuration generated by `create` consists of an `httpdconf` based version (in Python) which can then be used to generate an actual Apache configuration (by using the `genconfig` subcommand or simply executing the config files itself). The idea is that the Apache configuration is always generated and the Python version is the one meant for editing/adjustments.

The `create` subcommand will create the necessary files and directories if they do not exist, but will not overwrite any existing files or directories only producing a warning when a file or directory already exists. It will abort if the Python version of the configuration file already exists.

`create` requires a single argument: the distination directory, Apache `ServerRoot`.

`create` has the following command options:

--listen

  A string describing the port and optional IP address on which the server is to listen for incoming requests in the form `[ip_address:]port` The argument will be applied to the Apache `Listen` directive as is and therefore must be syntactically compatible with it.

--pythonpath

  A colon (`":"`) separate list of paths to be applied to the PythonPath directive.

--pythonhandler

  The name of the Python handler to use. Applied to the PythonHandler directive.

--pythonoption

  An option to be specified in the configuration. Multiple options are alowed. Applied to the PythonOption directive.

### genconfig

This sub-command exists to facilitate re-generation of an Apache configuration from a Python-based one. All it does is run the script, but its use is recommended because the mod_python command will execute the correct version of Python under which mod_python was initially compiled. Example:

    mod_python genconfig /path/to/server_root/httpd_conf.py > /path/to/server_root/httpd.conf

### start

Starts an Apache instance. Requires a single argument, the path to Apache configuration file.

### stop

Stops an Apache instance (using graceful-stop). Requires a single argument, the path to Apache configuration file.

### restart

Stops an Apache instance (using graceful). Requires a single argument, the path to Apache configuration file.

### version

This sub-command prints out version and location information about this mod_python installation, the Apache HTTP Server and Python used when building this mod_python instance.

### Example

To create an Apache instance with all the required directories for a WSGI application which is located in `/path/to/myapp` and defined in `/path/to/myapp/myapp/myapp/wsgi.py`, run the following:

    mod_python create /path/to/new/server_root \
        --pythonpath=/path/to/my/app \
        --pythonhandler=mod_python.wsgi \
        --pythonoption="mod_python.wsgi.application myapp.wsgi::application"

The above example will create a Python-based configuration in `/path/to/new/server_root/conf/http_conf.py` which is a simple Python script. When executed, the output of the script becomes an Apache configuration (`create` will take care of generating the first Apache config for you).

You should be able to run this Apache instance by executing:

    mod_python start /path/to/new/server_root/conf/httpd.conf