Skip to content

Commit

Permalink
ceph-rest-api: clean up options/environment
Browse files Browse the repository at this point in the history 
ceph-rest-api:
* create app from wrapper by calling generate_app()
* pass args to generate_app() (early parsed in wrapper)
* parse -i/--id here as well
* set addr:port on returned app object
* handle only EnvironmentError exceptions; let others spew traceback
* turn off debug when running singlethreaded server

ceph_rest_api.py:
* put glob.* on app.ceph_* instead; pass around app in init code
* drop conf parsing (let librados do its job)

Documentation updated to match.

Signed-off-by: Dan Mick <[email protected]>
Reviewed-by: Sage Weil <[email protected]>
  • Loading branch information
Dan Mick committed Jul 27, 2013
1 parent 629326a commit 8af4775
Show file tree
Hide file tree
Showing 4 changed files with 188 additions and 220 deletions.
75 changes: 46 additions & 29 deletions doc/man/8/ceph-rest-api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
Synopsis
========

| **ceph-rest-api** [ -c *conffile* ] [ -n *name* ... ]
| **ceph-rest-api** [ -c *conffile* ] [--cluster *clustername* ] [ -n *name* ] [-i *id* ]

Description
Expand All @@ -21,7 +21,7 @@ command-line tool through an HTTP-accessible interface.
Options
=======

.. option:: -c/--conf *conffile*
.. option:: -c/--conf conffile

names the ceph.conf file to use for configuration. If -c is not
specified, the default depends on the state of the --cluster option
Expand All @@ -35,38 +35,49 @@ Options

so you can also pass this option in the environment as CEPH_CONF.

.. option:: --cluster *clustername*
.. option:: --cluster clustername

set *clustername* for use in the $cluster metavariable, for
locating the ceph.conf file. The default is 'ceph'.
You can also pass this option in the environment as
CEPH_CLUSTER_NAME.

.. option:: -n/--name *name*
.. option:: -n/--name name

specifies the client 'name', which is used to find the
client-specific configuration options in the config file, and
also is the name used for authentication when connecting
to the cluster (the entity name appearing in ceph auth list output,
for example). The default is 'client.restapi'. You can also
pass this option in the environment as CEPH_NAME.
for example). The default is 'client.restapi'.

.. option:: -i/--id id

specifies the client 'id', which will form the clientname
as 'client.<id>' if clientname is not set. If -n/-name is
set, that takes precedence.

Also, global Ceph options are supported.


Configuration parameters
========================

Supported configuration parameters include:

* **restapi client name** the 'clientname' used for auth and ceph.conf
* **restapi keyring** the keyring file holding the key for 'clientname'
* **restapi public addr** ip:port to listen on (default 0.0.0.0:5000)
* **keyring** the keyring file holding the key for 'clientname'
* **public addr** ip:port to listen on (default 0.0.0.0:5000)
* **log file** (usual Ceph default)
* **restapi base url** the base URL to answer requests on (default /api/v0.1)
* **restapi log level** critical, error, warning, info, debug
* **restapi log file** (default /var/local/ceph/<clientname>.log)
* **restapi log level** critical, error, warning, info, debug (default warning)

Configuration parameters are searched in the standard order:
first in the section named '<clientname>', then 'client', then 'global'.

A server will run on **restapi public addr** if the ceph-rest-api
executed directly; otherwise, configuration is specified by the
enclosing WSGI web server.
<clientname> is either supplied by -n/--name, "client.<id>" where
<id> is supplied by -i/--id, or 'client.restapi' if neither option
is present.

A single-threaded server will run on **public addr** if the ceph-rest-api
executed directly; otherwise, configuration is specified by the enclosing
WSGI web server.

Commands
========
Expand All @@ -92,7 +103,9 @@ with a small description of each command, is provided when the requested
path is incomplete/partially matching. Requesting / will redirect to
the value of **restapi base url**, and that path will give a full list
of all known commands. The command set is very similar to the commands
supported by the **ceph** tool.
supported by the **ceph** tool. One notable exception is that the
``ceph pg <pgid> <command>`` style of commands is supported here
as ``tell/<pgid>/command?args``.

Deployment as WSGI application
==============================
Expand All @@ -101,18 +114,22 @@ When deploying as WSGI application (say, with Apache/mod_wsgi,
or nginx/uwsgi, or gunicorn, etc.), use the ``ceph_rest_api.py`` module
(``ceph-rest-api`` is a thin layer around this module). The standalone web
server is of course not used, so address/port configuration is done in
the WSGI server. Also, configuration switches are not passed; rather,
environment variables are used:

* CEPH_CONF holds -c/--conf
* CEPH_CLUSTER_NAME holds --cluster
* CEPH_NAME holds -n/--name

Any errors reading configuration or connecting to the cluster cause
ImportError to be raised with a descriptive message on import; see
your WSGI server documentation for how to see those messages in case
of problem.

the WSGI server. Use a python .wsgi module or the equivalent to call
``app = generate_app(conf, cluster, clientname, clientid, args)`` where:

* conf is as -c/--conf above
* cluster is as --cluster above
* clientname, -n/--name
* clientid, -i/--id, and
* args are any other generic Ceph arguments

When app is returned, it will have attributes 'ceph_addr' and 'ceph_port'
set to what the address and port are in the Ceph configuration;
those may be used for the server, or ignored.

Any errors reading configuration or connecting to the cluster cause an
exception to be raised; see your WSGI server documentation for how to
see those messages in case of problem.

Availability
============
Expand Down
76 changes: 48 additions & 28 deletions man/ceph-rest-api.8
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.TH "CEPH-REST-API" "8" "July 12, 2013" "dev" "Ceph"
.TH "CEPH-REST-API" "8" "July 26, 2013" "dev" "Ceph"
.SH NAME
ceph-rest-api \- ceph RESTlike administration server
.
Expand Down Expand Up @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.
.SH SYNOPSIS
.nf
\fBceph\-rest\-api\fP [ \-c \fIconffile\fP ] [ \-n \fIname\fP ... ]
\fBceph\-rest\-api\fP [ \-c \fIconffile\fP ] [\-\-cluster \fIclustername\fP ] [ \-n \fIname\fP ] [\-i \fIid\fP ]
.fi
.sp
.SH DESCRIPTION
Expand All @@ -44,7 +44,7 @@ command\-line tool through an HTTP\-accessible interface.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-c/\-\-conf *conffile*
.B \-c/\-\-conf conffile
names the ceph.conf file to use for configuration. If \-c is not
specified, the default depends on the state of the \-\-cluster option
(default \(aqceph\(aq; see below). The configuration file is searched
Expand All @@ -64,43 +64,54 @@ so you can also pass this option in the environment as CEPH_CONF.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cluster *clustername*
.B \-\-cluster clustername
set \fIclustername\fP for use in the $cluster metavariable, for
locating the ceph.conf file. The default is \(aqceph\(aq.
You can also pass this option in the environment as
CEPH_CLUSTER_NAME.
.UNINDENT
.INDENT 0.0
.TP
.B \-n/\-\-name *name*
.B \-n/\-\-name name
specifies the client \(aqname\(aq, which is used to find the
client\-specific configuration options in the config file, and
also is the name used for authentication when connecting
to the cluster (the entity name appearing in ceph auth list output,
for example). The default is \(aqclient.restapi\(aq. You can also
pass this option in the environment as CEPH_NAME.
for example). The default is \(aqclient.restapi\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-i/\-\-id id
specifies the client \(aqid\(aq, which will form the clientname
as \(aqclient.<id>\(aq if clientname is not set. If \-n/\-name is
set, that takes precedence.
.sp
Also, global Ceph options are supported.
.UNINDENT
.SH CONFIGURATION PARAMETERS
.sp
Supported configuration parameters include:
.INDENT 0.0
.IP \(bu 2
\fBrestapi client name\fP the \(aqclientname\(aq used for auth and ceph.conf
\fBkeyring\fP the keyring file holding the key for \(aqclientname\(aq
.IP \(bu 2
\fBrestapi keyring\fP the keyring file holding the key for \(aqclientname\(aq
\fBpublic addr\fP ip:port to listen on (default 0.0.0.0:5000)
.IP \(bu 2
\fBrestapi public addr\fP ip:port to listen on (default 0.0.0.0:5000)
\fBlog file\fP (usual Ceph default)
.IP \(bu 2
\fBrestapi base url\fP the base URL to answer requests on (default /api/v0.1)
.IP \(bu 2
\fBrestapi log level\fP critical, error, warning, info, debug
.IP \(bu 2
\fBrestapi log file\fP (default /var/local/ceph/<clientname>.log)
\fBrestapi log level\fP critical, error, warning, info, debug (default warning)
.UNINDENT
.sp
A server will run on \fBrestapi public addr\fP if the ceph\-rest\-api
executed directly; otherwise, configuration is specified by the
enclosing WSGI web server.
Configuration parameters are searched in the standard order:
first in the section named \(aq<clientname>\(aq, then \(aqclient\(aq, then \(aqglobal\(aq.
.sp
<clientname> is either supplied by \-n/\-\-name, "client.<id>" where
<id> is supplied by \-i/\-\-id, or \(aqclient.restapi\(aq if neither option
is present.
.sp
A single\-threaded server will run on \fBpublic addr\fP if the ceph\-rest\-api
executed directly; otherwise, configuration is specified by the enclosing
WSGI web server.
.SH COMMANDS
.sp
Commands are submitted with HTTP GET requests (for commands that
Expand All @@ -122,28 +133,37 @@ with a small description of each command, is provided when the requested
path is incomplete/partially matching. Requesting / will redirect to
the value of \fBrestapi base url\fP, and that path will give a full list
of all known commands. The command set is very similar to the commands
supported by the \fBceph\fP tool.
supported by the \fBceph\fP tool. One notable exception is that the
\fBceph pg <pgid> <command>\fP style of commands is supported here
as \fBtell/<pgid>/command?args\fP.
.SH DEPLOYMENT AS WSGI APPLICATION
.sp
When deploying as WSGI application (say, with Apache/mod_wsgi,
or nginx/uwsgi, or gunicorn, etc.), use the \fBceph_rest_api.py\fP module
(\fBceph\-rest\-api\fP is a thin layer around this module). The standalone web
server is of course not used, so address/port configuration is done in
the WSGI server. Also, configuration switches are not passed; rather,
environment variables are used:
the WSGI server. Use a python .wsgi module or the equivalent to call
\fBapp = generate_app(conf, cluster, clientname, clientid, args)\fP where:
.INDENT 0.0
.IP \(bu 2
CEPH_CONF holds \-c/\-\-conf
conf is as \-c/\-\-conf above
.IP \(bu 2
cluster is as \-\-cluster above
.IP \(bu 2
CEPH_CLUSTER_NAME holds \-\-cluster
clientname, \-n/\-\-name
.IP \(bu 2
CEPH_NAME holds \-n/\-\-name
clientid, \-i/\-\-id, and
.IP \(bu 2
args are any other generic Ceph arguments
.UNINDENT
.sp
Any errors reading configuration or connecting to the cluster cause
ImportError to be raised with a descriptive message on import; see
your WSGI server documentation for how to see those messages in case
of problem.
When app is returned, it will have attributes \(aqceph_addr\(aq and \(aqceph_port\(aq
set to what the address and port are in the Ceph configuration;
those may be used for the server, or ignored.
.sp
Any errors reading configuration or connecting to the cluster cause an
exception to be raised; see your WSGI server documentation for how to
see those messages in case of problem.
.SH AVAILABILITY
.sp
\fBceph\-rest\-api\fP is part of the Ceph distributed file system. Please refer to the Ceph documentation at
Expand Down
31 changes: 16 additions & 15 deletions src/ceph-rest-api
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,34 +33,35 @@ def parse_args():
parser.add_argument('-c', '--conf', help='Ceph configuration file')
parser.add_argument('--cluster', help='Ceph cluster name')
parser.add_argument('-n', '--name', help='Ceph client name')
parser.add_argument('-i', '--id', help='Ceph client id')

return parser.parse_args()

return parser.parse_known_args()

# main

parsed_args = parse_args()
if parsed_args.conf:
os.environ['CEPH_CONF'] = parsed_args.conf
if parsed_args.cluster:
os.environ['CEPH_CLUSTER_NAME'] = parsed_args.cluster
if parsed_args.name:
os.environ['CEPH_NAME'] = parsed_args.name
parsed_args, rest = parse_args()

# import now that env vars are available to imported module

try:
import ceph_rest_api
except Exception as e:
except EnvironmentError as e:
print >> sys.stderr, "Error importing ceph_rest_api: ", str(e)
sys.exit(1)

# importing ceph_rest_api has set module globals 'app', 'addr', and 'port'
# let other exceptions generate traceback

app = ceph_rest_api.generate_app(
parsed_args.conf,
parsed_args.cluster,
parsed_args.name,
parsed_args.id,
rest,
)

files = [os.path.split(fr[1])[-1] for fr in inspect.stack()]
if 'pdb.py' in files:
ceph_rest_api.app.run(host=ceph_rest_api.addr, port=ceph_rest_api.port,
debug=True, use_reloader=False, use_debugger=False)
app.run(host=app.ceph_addr, port=app.ceph_port,
debug=True, use_reloader=False, use_debugger=False)
else:
ceph_rest_api.app.run(host=ceph_rest_api.addr, port=ceph_rest_api.port,
debug=True)
app.run(host=app.ceph_addr, port=app.ceph_port)
Loading

0 comments on commit 8af4775

Please sign in to comment.