From 884cf82f4b41868af93391130d558e1488de1083 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 1 Sep 2007 03:58:17 +0000 Subject: Print error messages for unknown commands. Rewrite the command docs to use a better convention for command arguments and to include quite a few more details. --- server/wallet-backend | 146 +++++++++++++++++++++++++++++++------------------- 1 file changed, 90 insertions(+), 56 deletions(-) (limited to 'server') diff --git a/server/wallet-backend b/server/wallet-backend index caab409..2e6284e 100755 --- a/server/wallet-backend +++ b/server/wallet-backend @@ -80,6 +80,8 @@ if ($command eq 'acl') { } elsif ($action eq 'rename') { check_args (2, [], @args); $server->acl_rename (@args) or die $server->error; + } else { + die "unknown command acl $action\n"; } } elsif ($command eq 'create') { check_args (2, [], @args); @@ -149,6 +151,8 @@ if ($command eq 'acl') { } elsif ($command eq 'store') { check_args (3, [2], @args); $server->store (@args) or die $server->error; +} else { + die "unknown command $command\n"; } exit 0; __END__ @@ -188,94 +192,124 @@ B takes no traditional options. =head1 COMMANDS -The following commands are recognized. Only brief descriptions are given -here, along with any special notes about the output as formatted by -B. - -Most commands can only be executed by someone authorized by the ADMIN ACL. -The exceptions are get and store, which are authorized by the get and store -ACLs if set and otherwise the owner ACL and to which the ADMIN ACL does not -apply; show, which requires either the ADMIN ACL or checks the show ACL and -the owner ACL if the show ACL isn't set; and destroy, which requires either -the ADMIN ACL or the destroy ACL. +Most commands are only available to wallet administrators (users on the +C ACL). The exceptions are C, C, C, and +C. All of those commands have their own ACLs, and if the +appropriate ACL is set, it alone is checked to see if the user has access. +Otherwise, C, C, and C access is permitted if the user is +authorized by the owner ACL of the object. -For complete details, including the authorization model for who can execute -which command, see Wallet::Server(3). +Administrators can run any command on any object or ACL except for C +and C. For C and C, they must still be authorized by +either the appropriate specific ACL or the owner ACL. =over 4 -=item acl add ID SCHEME IDENTIFIER +=item acl add -Adds an entry with SCHEME and IDENTIFIER to the ACL ID. +Adds an entry with and to the ACL . may be +either the name of an ACL or its numeric identifier. -=item acl create NAME +=item acl create -Create a new ACL with name NAME. +Create a new, empty ACL with name . When setting an ACL on an +object with a set of entries that don't match an existing ACL, first +create a new ACL with C, add the appropriate entries to it +with C, and then set the ACL on an object with the C or +C commands. -=item acl destroy ID +=item acl destroy -Destroy the ACL ID (which must not be reference by any object). +Destroy the ACL . This ACL must no longer be referenced by any object +or the ACL destruction will fail. The special ACL named C cannot +be destroyed. -=item acl remove ID SCHEME IDENTIFIER +=item acl remove -Remove the entry with SCHEME and IDENTIFIER from the ACL ID. +Remove the entry with and from the ACL . +may be either the name of an ACL or its numeric identifier. The last +entry in the special ACL C cannot be removed to protect against +accidental lockout, but administrators can remove themselves from the +C ACL and can leave only a non-functioning entry on the ACL. Use +caution when removing entries from the C ACL. -=item create TYPE NAME +=item create -Create a new object with TYPE and NAME and no ACLs set. +Create a new object of type with name . With some backends, +this will trigger creation of an entry in an external system as well. +The new object will have no ACLs and no owner set, so usually the +administrator will want to then set an owner with C so that the +object will be usable. -=item destroy TYPE NAME +=item destroy -Destroy the object identified by TYPE and NAME. +Destroy the object identified by and . With some backends, +this will trigger destruction of an object in an external system as well. -=item expires TYPE NAME [EXPIRES] +=item expires [] -If EXPIRES is not given, displays the current expiration of the object -identified by TYPE and NAME, or C if none is set. If -EXPIRES is given, sets the expiration on the object identified by TYPE and -NAME to EXPIRES, which should be in seconds since epoch. +If is not given, displays the current expiration of the object +identified by and , or C if none is set. +The expiration will be displayed in seconds since epoch. -=item get TYPE NAME +If is given, sets the expiration on the object identified by + and to . should be given in seconds +since epoch. If is the empty string, clears the expiration of +the object. -Prints to standard output the data associated with the object identified by -TYPE and NAME. This may trigger generation of new data and invalidate old -data for that object depending on the object type. +Currently, the expiration of an object is not used. -=item getacl TYPE NAME ACL +=item get -Prints the ACL of type ACL, which must be one of C, C, C, -C, or C, for the object identified by TYPE and NAME. Prints -C if that ACL isn't set. +Prints to standard output the data associated with the object identified +by and , or stores it in a file if the B<-f> option was +given. This may trigger generation of new data and invalidate old data +for that object depending on the object type. -=item owner TYPE NAME [OWNER] +=item getacl -If OWNER is not given, displays the ACL name of the current owner of the -object identified by TYPE and NAME, or C if none is set. If -OWNER is given, sets the owner of the object identified by TYPE and NAME to -OWNER. +Prints the ACL , which must be one of C, C, C, +C, or C, for the object identified by and . +Prints C if that ACL isn't set on that object. Remember that +if the C, C, or C ACLs aren't set, authorization falls +back to checking the owner ACL. See the C command for displaying +or setting it. -=item setacl TYPE NAME ACL ID +=item owner [] -Sets the ACL type ACL, which must be one of C, C, C, -C, or C, to ID on the object identified by TYPE and NAME. +If is not given, displays the current owner ACL of the object +identified by and , or C if none is set. The +result will be the name of an ACL. -=item show TYPE NAME +If is given, sets the owner of the object identified by and + to . If is the empty string, clears the owner of +the object. -Displays the current object metadata for the object identified by TYPE and -NAME. +=item setacl -=item store TYPE NAME DATA +Sets the ACL , which must be one of C, C, C, +C, or C, to on the object identified by and +. If is the empty string, clears that ACL on the object. -Stores DATA for the object identified by TYPE and NAME for later retrieval -with get. Not all object types support this. +=item show -=back +Displays the current object metadata for the object identified by +and . This human-readable output will show the object type and +name, the owner, any specific ACLs set on the object, the expiration if +any, and the user, remote host, and time when the object was created, last +stored, and last downloaded. -=head1 EXIT STATUS +=item store -Regular output is printed to standard output and errors are printed to -standard error. If the command was successful, B exits with -status 0. If it failed, B exits with a non-zero status. +Stores for the object identified by and for later +retrieval with C. Not all object types support this. + +Currently, is limited to not containing nul characters and may +therefore not be binary data, and is limited by the maximum command line +length of the operating system of the wallet server. These restrictions +will be lifted in the future. + +=back =head1 SEE ALSO -- cgit v1.2.3