bionic (8) ceph-rest-api.8.gz

NAME

       ceph-rest-api - ceph RESTlike administration server

SYNOPSIS

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

DESCRIPTION

       ceph-rest-api  is  a  WSGI application that can run as a standalone web service or run under a web server
       that supports WSGI.  It provides much of the functionality of  the  ceph  command-line  tool  through  an
       HTTP-accessible interface.

OPTIONS

       -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 'ceph'; see below).  The configuration file is searched
              for in this order:

              • $CEPH_CONF

              • /etc/ceph/${cluster}.conf

              • ~/.ceph/${cluster}.conf

              • ${cluster}.conf (in the current directory)

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

       --cluster clustername
              set  clustername  for  use  in  the  $cluster  metavariable, for locating the ceph.conf file.  The
              default is 'ceph'.

       -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 ls' output, for example).  The default is 'client.restapi'.

       -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:

       • 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 (default warning)

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

       <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

       Commands are submitted with HTTP GET requests (for commands that  primarily  return  data)  or  PUT  (for
       commands  that  affect  cluster state).  HEAD and OPTIONS are also supported.  Standard HTTP status codes
       are returned.

       For commands that return  bulk  data,  the  request  can  include  Accept:  application/json  or  Accept:
       application/xml  to  select the desired structured output, or you may use a .json or .xml addition to the
       requested PATH.  Parameters are supplied as query parameters in the request;  for  parameters  that  take
       more  than  one  value,  repeat  the key=val construct.  For instance, to remove OSDs 2 and 3, send a PUT
       request to osd/rm?ids=2&ids=3.

DISCOVERY

       Human-readable discovery of supported commands and parameters, along 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.
       For  example,  requesting api/vX.X/mon will return the list of API calls for monitors - api/vX.X/osd will
       return the list of API calls for OSD and so on.

       The command set is very similar to the commands 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

       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.  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

       ceph-rest-api  is  part  of  Ceph,  a massively scalable, open-source, distributed storage system. Please
       refer to the Ceph documentation at http://ceph.com/docs for more information.

SEE ALSO

       ceph(8)

COPYRIGHT

       2010-2023, Inktank Storage, Inc. and contributors. Licensed  under  Creative  Commons  Attribution  Share
       Alike 3.0 (CC-BY-SA-3.0)