Documentation for ceph-rest-api

Jan 1, 2014 dmsimard

I learned that there was a Ceph REST API and I experimented with it a bit.

I said the documentation was lacking and I take that back, I didn’t catch on that the API documentation was built into the application. I opened a pull request to make the documentation a bit more explicit about that: https://github.com/ceph/ceph/pull/1026

Here’s what the API documentation currently looks like:

Possible commands:	Method	Description
auth/add?entity=entity()&caps={c
aps() [...]}	PUT	add auth info forfrom input file, or random key if no input given, and/or any caps specified in the command
auth/caps?entity=entity()&caps=c
aps() [...]	PUT	update caps forfrom caps specified in the command
auth/del?entity=entity()	PUT	delete all caps for
auth/export?entity={entity()}	GET	write keyring for requested entity, or master keyring if none given
auth/get?entity=entity()	GET	write keyring file with requested key
auth/get-key?entity=entity()	GET	display requested key
auth/get-or-create?entity=entity(<string
>)&caps={caps() [...]}	PUT	add auth info forfrom input file, or random key if no input given, and/or any caps specified in the command
auth/get-or-create-key?entity=entity(<st
ring>)&caps={caps()
[...]}	PUT	get, or add, key forfrom system/caps pairs specified in the command. If key already exists, any given caps must match the existing caps for that key.
auth/import	PUT	auth import: read keyring file from -i
auth/list	GET	list authentication state
auth/print-key?entity=entity()	GET	display requested key
auth/print_key?entity=entity()	GET	display requested key
tell//bench?count={count(
)}&size={size()}	PUT	OSD benchmark: write-byte objects, (default 1G size 4MB). Results in log.
compact	PUT	cause compaction of monitor's leveldb storage
config-key/del?key=key()	PUT	delete
config-key/exists?key=key()	GET	check for's existence
config-key/get?key=key()	GET	get
config-key/list	GET	list keys
config-key/put?key=key()&val={va
l()}	PUT	put, value
tell/<osdid-or-
pgid>/cpu_profiler?arg=arg(status	flush)	PUT
tell//debug/kick_recovery
_wq?delay=delay(<int[0-]>)	PUT	set osd_recovery_delay_start to
tell//debug_dump_missing?
filename=filename()	GET	dump missing objects to a named file
df?detail={detail}	GET	show cluster free space stats
tell/<osdid-or-
pgid>/dump_pg_recovery_stats	GET	dump pg recovery statistics
tell//flush_pg_stats	PUT	flush pg stats
fsid	GET	show cluster FSID/UUID
health?detail={detail}	GET	show cluster health
tell//heap?heapcmd=heapcm
d(dump	start_profiler	stop_profiler
ase	stats)	PUT
heap?heapcmd=heapcmd(dump	start_profiler
stop_profiler	release	stats)
tell//injectargs?injected
_args=injected_args()
[...]	PUT	inject configuration arguments into running OSD
injectargs?injected_args=injected_args(<
string>) [...]	PUT	inject config arguments into monitor
tell//list_missing?offset
={offset()}	GET	list missing objects on this pg, perhaps starting at an offset given in JSON
tell//list_missing?offset
={offset()}	PUT	list missing objects on this pg, perhaps starting at an offset given in JSON
log?logtext=logtext()
[...]	PUT	log supplied text to the monitor log
tell/<osdid-or-
pgid>/mark_unfound_lost?mulcmd=revert	PUT	mark all unfound objects in this pg as lost, either removing or reverting to a prior version if one is available
tell//mark_unfound_lost/r
evert?mulcmd=revert	PUT	mark all unfound objects in this pg as lost, either removing or reverting to a prior version if one is available
mds/add_data_pool?pool=pool()	PUT	add data pool
mds/cluster_down	PUT	take MDS cluster down
mds/cluster_up	PUT	bring MDS cluster up
mds/compat/rm_compat?feature=feature(<in
t[0-]>)	PUT	remove compatible feature
mds/compat/rm_incompat?feature=feature(<
int[0-]>)	PUT	remove incompatible feature
mds/compat/show	GET	show mds compatibility settings
mds/deactivate?who=who()	PUT	stop mds
mds/dump?epoch={epoch(<int[0-]>)}	GET	dump info, optionally from epoch
mds/fail?who=who()	PUT	force mds to status failed
mds/getmap?epoch={epoch(<int[0-]>)}	GET	get MDS map, optionally from epoch
mds/newfs?metadata=metadata(<int[0-]>)&d
ata=data(<int[0-]>)&sure={--yes-i
-really-mean-it}	PUT	make new filesystom using poolsand
mds/remove_data_pool?pool=pool()	PUT	remove data pool
mds/rm?gid=gid(<int[0-]>)&who=who(<name
(type.id)>)	PUT	remove nonactive mds
mds/rmfailed?who=who(<int[0-]>)	PUT	remove failed mds
mds/set?key=allow_new_snaps&sure={sure(<
string>)}	Unknown	set
mds/set_max_mds?maxmds=maxmds(<int[0-]>)	PUT	set max MDS index
mds/set_state?gid=gid(<int[0-]>)&state=s
tate(<int[0-20]>)	PUT	set mds state ofto
mds/setmap?epoch=epoch(<int[0-]>)	PUT	set mds map; must supply correct epoch number
mds/stat	GET	show MDS status
mds/stop?who=who()	PUT	stop mds
mds/tell?who=who()&args=args(<st
ring>) [...]	PUT	send command to particular mds
mds/unset?key=allow_new_snaps&sure={sure
()}	Unknown	unset
mon/add?name=name()&addr=addr(<I
Paddr[:port]>)	PUT	add new monitor namedat
mon/dump?epoch={epoch(<int[0-]>)}	GET	dump formatted monmap (optionally from epoch)
mon/getmap?epoch={epoch(<int[0-]>)}	GET	get monmap
mon/remove?name=name()	PUT	remove monitor named
mon/stat	GET	summarize monitor status
mon_status	GET	report status of monitors
osd/blacklist?blacklistop=blacklistop(ad
d	rm)&addr=addr()&expire={ex
pire(<float[0.0-]>)}	PUT	add (optionally untilseconds from now) or removefrom blacklist
osd/blacklist/ls	GET	show blacklisted clients
osd/create?uuid={uuid()}	PUT	create new osd (with optional UUID)
osd/crush/add?id=id(<osdname (id	osd.id)
>)&weight=weight(<float[0.0-]>)&args=arg
s(<string(goodchars [A-Za-z0-9-_.=])>)
[<string(goodchars [A-Za-z0-9-_.=])>...]	PUT	add or update crushmap position and weight forwithand location
osd/crush/add-
bucket?name=name(<string(goodchars
[A-Za-z0-9-_.])>)&type=type()	PUT	add no-parent (probably root) crush bucketof type
osd/crush/create-or-move?id=id(<osdname
(id	osd.id)>)&weight=weight(<float[0.0-]
>)&args=args(<string(goodchars
[A-Za-z0-9-_.=])>) [<string(goodchars
[A-Za-z0-9-_.=])>...]	PUT	create entry or move existing entry forat/to location
osd/crush/dump	GET	dump crush map
osd/crush/link?name=name()&args=
args(<string(goodchars
[A-Za-z0-9-_.=])>) [<string(goodchars
[A-Za-z0-9-_.=])>...]	PUT	link existing entry forunder location
osd/crush/move?name=name(<string(goodcha
rs [A-Za-z0-9-_.])>)&args=args(<string(g
oodchars [A-Za-z0-9-_.=])>)
[<string(goodchars [A-Za-z0-9-_.=])>...]	PUT	move existing entry forto location
osd/crush/remove?name=name(<string(goodc
hars [A-Za-z0-9-_.])>)&ancestor={ancesto
r(<string(goodchars [A-Za-z0-9-_.])>)}	PUT	removefrom crush map (everywhere, or just at
osd/crush/reweight?name=name(<string(goo
dchars [A-Za-z0-9-_.])>)&weight=weight(<
float[0.0-]>)	PUT	change's weight toin crush map
osd/crush/rm?name=name(<string(goodchars
[A-Za-z0-9-_.])>)&ancestor={ancestor(<st
ring(goodchars [A-Za-z0-9-_.])>)}	PUT	removefrom crush map (everywhere, or just at
osd/crush/rule/create-
simple?name=name(<string(goodchars [A-Za
-z0-9-_.])>)&root=root(<string(goodchars
[A-Za-z0-9-_.])>)&type=type(<string(good
chars [A-Za-z0-9-_.])>)	PUT	create crush ruleinof type
osd/crush/rule/dump	GET	dump crush rules
osd/crush/rule/list	GET	list crush rules
osd/crush/rule/ls	GET	list crush rules
osd/crush/rule/rm?name=name(<string(good
chars [A-Za-z0-9-_.])>)	PUT	remove crush rule
osd/crush/set	PUT	set crush map from input file
osd/crush/set?id=id(<osdname (id	osd.id)
>)&weight=weight(<float[0.0-]>)&args=arg
s(<string(goodchars [A-Za-z0-9-_.=])>)
[<string(goodchars [A-Za-z0-9-_.=])>...]	PUT	update crushmap position and weight fortowith location
osd/crush/tunables?profile=profile(legac
y	argonaut	bobtail
osd/crush/unlink?name=name(<string(goodc
hars [A-Za-z0-9-_.])>)&ancestor={ancesto
r(<string(goodchars [A-Za-z0-9-_.])>)}	PUT	unlinkfrom crush map (everywhere, or just at
osd/deep-scrub?who=who()	PUT	initiate deep scrub on osd
osd/down?ids=ids() [...]	PUT	set osd(s)[...] down
osd/dump?epoch={epoch(<int[0-]>)}	GET	print summary of OSD map
osd/find?id=id(<int[0-]>)	GET	find osdin the CRUSH map and show its location
osd/getcrushmap?epoch={epoch(<int[0-]>)}	GET	get CRUSH map
osd/getmap?epoch={epoch(<int[0-]>)}	GET	get OSD map
osd/getmaxosd	GET	show largest OSD id
osd/in?ids=ids() [...]	PUT	set osd(s)[...] in
osd/lost?id=id(<int[0-]>)&sure={--yes-i
-really-mean-it}	PUT	mark osd as permanently lost. THIS DESTROYS DATA IF NO MORE REPLICAS EXIST, BE CAREFUL
osd/ls?epoch={epoch(<int[0-]>)}	GET	show all OSD ids
osd/lspools?auid={auid()}	GET	list pools
osd/map?pool=pool()&object=obj
ect()	GET	find pg for
osd/out?ids=ids() [...]	PUT	set osd(s)[...] out
osd/pause	PUT	pause osd
osd/perf	GET	print dump of OSD perf summary stats
osd/pool/create?pool=pool()&pg
_num=pg_num(<int[0-]>)&pgp_num={pgp_num(
<int[0-]>)}&properties={properties(<stri
ng(goodchars [A-Za-z0-9-_.=])>)
[<string(goodchars
[A-Za-z0-9-_.=])>...]}	PUT	create pool
osd/pool/delete?pool=pool()&po
ol2={pool2()}&sure={--yes-i
-really-really-mean-it}	PUT	delete pool
osd/pool/get?pool=pool()&var=v
ar(size	min_size	crash_replay_interval
g_num	pgp_num	crush_ruleset)
osd/pool/mksnap?pool=pool()&sn
ap=snap()	PUT	make snapshotin
osd/pool/rename?srcpool=srcpool(<poolnam
e>)&destpool=destpool()	PUT	renameto
osd/pool/rmsnap?pool=pool()&sn
ap=snap()	PUT	remove snapshotfrom
osd/pool/set?pool=pool()&var=v
ar(size	min_size	crash_replay_interval
g_num	pgp_num	crush_ruleset
val=val()	PUT	set pool parameter `to`
osd/pool/set-quota?pool=pool()
&field=field(max_objects	max_bytes)&val=
val()	PUT	set object or byte limit on pool
osd/pool/stats?name={name()}	GET	obtain stats from all pools, or from specified pool
osd/repair?who=who()	PUT	initiate repair on osd
osd/reweight?id=id(<int[0-]>)&weight=wei
ght(<float[0.0-1.0]>)	PUT	reweight osd to 0.0 << 1.0
osd/reweight-by-
utilization?oload={oload(<int[100-]>)}	PUT	reweight OSDs by utilization [overload-percentage-for-consideration, default 120]
osd/rm?ids=ids() [...]	PUT	remove osd(s)[...] in
osd/scrub?who=who()	PUT	initiate scrub on osd
osd/set?key=key(pause	noup	nodown
noin	nobackfill	norecover
nodeep-scrub)	PUT	set
osd/setcrushmap	PUT	set crush map from input file
osd/setmaxosd?newmax=newmax(<int[0-]>)	PUT	set new maximum osd value
osd/stat	GET	print summary of OSD map
osd/thrash?num_epochs=num_epochs(<int[0-
]>)	PUT	thrash OSDs for <num_epochs>
osd/tier/add?pool=pool()&tierp
ool=tierpool()	PUT	add the tierto base pool
osd/tier/cache-mode?pool=pool(
)&mode=mode(none	writeback	invalidate+fo
rward	readonly)	PUT
osd/tier/remove?pool=pool()&ti
erpool=tierpool()	PUT	remove the tierfrom base pool
osd/tier/remove-
overlay?pool=pool()	PUT	remove the overlay pool for base pool
osd/tier/set-overlay?pool=pool(<poolname
>)&overlaypool=overlaypool()	PUT	set the overlay pool for base poolto be
osd/tree?epoch={epoch(<int[0-]>)}	GET	print OSD tree
osd/unpause	PUT	unpause osd
osd/unset?key=key(pause	noup	nodown
t	noin	nobackfill
nodeep-scrub)	PUT	unset
pg/debug?debugop=debugop(unfound_objects
_exist	degraded_pgs_exist)	GET
pg/deep-scrub?pgid=pgid()	PUT	start deep-scrub on
pg/dump?dumpcontents={dumpcontents(all	s
ummary	sum	delta
f) [all	summary	sum
pgs_brief...]}	GET	show human-readable versions of pg map (only 'all' valid with plain)
pg/dump_json?dumpcontents={dumpcontents(
all	summary	sum
[all	summary	sum
pg/dump_pools_json	GET	show pg pools info in json only
pg/dump_stuck?stuckops={stuckops(inactiv
e	unclean	stale) [inactive
...]}&threshold={threshold()}	GET	show information about stuck pgs
pg/force_create_pg?pgid=pgid()	PUT	force creation of pg
pg/getmap	GET	get binary pg map to -o/stdout
pg/map?pgid=pgid()	GET	show mapping of pg to osds
pg/repair?pgid=pgid()	PUT	start repair on
pg/scrub?pgid=pgid()	PUT	start scrub on
pg/send_pg_creates	PUT	trigger pg creates to be issued
pg/set_full_ratio?ratio=ratio(<float[0.0
-1.0]>)	PUT	set ratio at which pgs are considered full
pg/set_nearfull_ratio?ratio=ratio(<float
[0.0-1.0]>)	PUT	set ratio at which pgs are considered nearly full
pg/stat	GET	show placement group status.
tell//query	GET	show details of a specific pg
tell//query	GET	show details of a specific pg
quorum?quorumcmd=quorumcmd(enter	exit)	PUT
quorum_status	GET	report status of monitor quorum
report?tags={tags()
[...]}	GET	report full status of cluster, optional title tag strings
tell/<osdid-or-
pgid>/reset_pg_recovery_stats	PUT	reset pg recovery statistics
scrub	PUT	scrub the monitor stores
status	GET	show cluster status
sync/force?validate1={--yes-i-really-
mean-it}&validate2={--i-know-what-i-am-
doing}	PUT	force sync of and clear monitor store
tell?target=target(<name
(type.id)>)&args=args()
[...]	PUT	send a command to a specific daemon
tell//version	GET	report version of OSD

Enjoy !