Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CEPH-REST-API(8)		     Ceph		      CEPH-REST-API(8)

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

	      o	$CEPH_CONF

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

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

	      o	${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	locat-
	      ing 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:

       o keyring the keyring file holding the key for 'clientname'

       o public	addr ip:port to	listen on (default 0.0.0.0:5000)

       o log file (usual Ceph default)

       o restapi  base	url  the  base	URL  to	 answer	 requests  on (default
	 /api/v0.1)

       o 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 enclos-
       ing WSGI	web server.

COMMANDS
       Commands	are submitted with HTTP	GET requests (for commands  that  pri-
       marily  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: ap-
       plication/json or Accept: application/xml to select the desired	struc-
       tured  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  re-
       quested path is incomplete/partially matching.  Requesting / will redi-
       rect 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 ng-
       inx/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:

       o conf is as -c/--conf above

       o cluster is as --cluster above

       o clientname, -n/--name

       o clientid, -i/--id, and

       o 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 configura-
       tion; 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,  dis-
       tributed	 storage  system.  Please  refer  to the Ceph documentation at
       http://ceph.com/docs for	more information.

SEE ALSO
       ceph(8)

COPYRIGHT
       2010-2014, Inktank Storage, Inc.	and contributors. Licensed under  Cre-
       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)

dev				 Aug 27, 2020		      CEPH-REST-API(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CONFIGURATION PARAMETERS | COMMANDS | DISCOVERY | DEPLOYMENT AS WSGI APPLICATION | AVAILABILITY | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ceph-rest-api&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help