The 'Omixed Server Administration Console' (hereafter AdminConsole) is a command-line based tool which allows administrators to control a running omixed server. The main features of the console:
Before attempting to interact with the omixed administration console it is useful to have an reasonable understanding of the basic concepts behind it. The Omixed Server Overview document provides an overview of the omixed design philosophy and explains some key terminology.
The AdminConsole is a Java application packaged in a JAR file. It is generated as part of the normal server compilation process and will be found in the top-level directory of your omixed installation.
The application can be used interactively by entering commands at the command prompt, or it can be used in batch mode by passing one or more commands as arguments to the application.
Most commands take one or more parameters. If the parameters are not provided as part of the command, they will be prompted for interactively.
The tool has a limited amount of built-in help which is accessible using the help command. Used on its own, the command will generate a list of all commands (and show their required parameters). The help command can also be used with a single parameter identifying one or more commands for which more information should be shown. For example help user lists all of the commands which have "user" in their name. Commands listed via this search are accompanied with a short description of what the command does.
All of the capabilities of the AdminConsole are achieved by talking to the 'admin' interface of the omixed server. This interface is implemented in the same way as the normal 'server' interface which means that the administration functionality can be easily accessed programmatically from any language or application.
As it is a text mode application, the AdminConsole must be run from a command shell.
On Windows® platforms run the program cmd.exe to get a suitable shell. On Macintosh® systems use the terminal application (in the 'Utilities' folder).
The AdminConsole is run using the java command with the -jar flag, like this:
If the java program is not in your path (i.e. it is not found automatically) you will get an error message from your shell saying that java is not recognised. In this case, you will need to either adjust your path, or provide the path to your java program explicitly.
When it starts, you will be prompted for a series of parameters to identify the server that you wish to connect to. Default values are provided for each of these and can be used by just pressing RETURN without entering a value.
The parameters are:
The host name (or IP address) of the machine running the server. The default value is 'localhost'.
The HTTPS port that the server is listening to. The default value is 8081. Note that the AdminConsole uses HTTPS not HTTP.
The path to the servers REST interface. The default value should be correct unless you have changed the service path in your application server configuration.
The name of the user that you wish to connect as. The special 'admin' user is automatically created when omixed is installed and will always be available. The 'admin' user has maximum privileges and can use all of the administration methods. The security policy system can be used to grant privileges to ordinary users.
The password for the chosen account. If you are using the special 'admin' account then the password will is specified in the 'omixed.properties' file.
If the connection is established successfully, a short message will be displayed and the command prompt will appear.
Alternatively, if there was some problem in connecting, an error message will be displayed and the AdminConsole will terminate.
Each of the four connection parameters can be provided as command line arguments to the AdminConsole, see the command line arguments reference section for details.
The resourceCreate command adds a new resource. It takes a single parameter which is the name of the resource. White-space, punctuation characters or non-printing characters are not allowed in resource names.
If the resource is created successfully, the server will respond with an "OK" message. Otherwise, an error message will be displayed.
A schema file is loaded into a resource using the resourceSetSchema command. This takes two parameters, the name of the resource and a URL pointing to the schema to be loaded.
The URL can use the HTTP or FILE protocols, but the protocol must always be specified. In the case of file URLs, the file path must be visible to the machine running the omixed server (which is not necessarily the same as the machine running the AdminConsole).
IMPORTANT! Loading a schema into a resource will remove all data that resource, including any forum posts and uploaded files.
If the schema loads successfully, you will get an "OK" message. Otherwise, if the schema file cannot be found, or is found to contain a syntax error, an error message will be displayed.
You can discover which schema a particular resource is using with resourceGetSchema command. The two parameters for this command specify a resource and a local file name into which the schema for that resource will be written.
A resource can be emptied deleted using the resourceEmpty command. This command irrevocably removes all items, tags, fora and uploaded files from a resource.
A resource can be deleted using the resourceDelete command. This command not only removes all of the contents of the resource, as per the resourceEmpty command but also removes the resource itself.
The omixed server supports three classes of account: A user account represents a normal user who will have the capability to create, browse and update their own items. A more restricted type of account is a guest account, which does not have the ability to create new items, only to browse existing items. Conversely, a more powerful type of account is the manager account, to which normal item permissions do not apply. Manager accounts can browse and edit all items in the resource regardless of who the items belong to.
User accounts exist and are managed independently of resources. Each user can be granted permission to connect to any subset of the resources managed by the server (see here).
User accounts are created using the userCreate command which takes three parameters: the user name, the account class and the password. As with all commands, if the parameters are not provided as part of the command, they will be prompted for interactively. If you are entering the password interactively, then it will not be echoed to the screen as you type, for example:
Note that a newly created account will not be able to log into any resources until a security policy which explicitly permits the login has been created.
The password for an account can be changed at any time using the userSetPassword command. This command takes two parameters, the user name and the new password.
The account class can be changed at any time using the userSetClass command. This command takes two parameters, the user name and the new account class.
It is not currently possible to delete user accounts (as they might be associated with data items). Until this facility is added, a user can be easily prevented from using their account by simply changing its password.
The userListAll command displays a list of the user accounts and their account types. This command takes an optional "filter" argument which can be used to filter the resulting list of users based on a regular expression (using Java syntax). For example the command "userListAll jim" would display only those usernames which contain the string "jim".
The userDescribe command takes a single parameter identifying a particular user and displays detailed information about that account, including the class, which user groups they belong to and which access groups apply to them.
A user group is simply a named collection of one or more users. They are used as a convenience when creating access groups or setting up security policies.
There is a special user group named everybody that is automatically defined and that always contains the full set of defined users. It is not possible to modify this user group directly.
A new user group is created using the userGroupCreate command which takes a single parameter, the name of the new group. User group names must be unique, and must not be the same as the name of any user.
User group names cannot contain any white-space. Although there is no restriction on the length of an user group name, or on the use of punctuation, it is suggested that names are kept reasonably short and simple.
A user group can be permanently deleted using the userGroupDelete command. It is not possible to delete a user group if it is a member of some other user group. It must be removed from any groups that it is a member of prior to being deleted.
A user or user group can be added to an existing user group using the userGroupAddMember command. The command requires two parameters, the name of the user group to modify and the name of a user or other user group to add.
Consider the following sequence of commands:
Two user groups are constructed, G1 and G2. G2 contains all of the members of G1 and also user U3. If additional users are added to G1, they will also become members of G2. Similarly, if members are removed from G1, they will be removed from G2.
Warning! It is not advisable to construct cyclic connections, i.e. a user group which is a member of itself, or a member of some other user group which is a member of itself.
Removing a member from a user group is achieved with the userGroupRemoveMember command. The command requires two parameters, the name of the user group to modify and the name of a user or other user group to remove. Removing a member from a group does not delete that member, it merely disassociates it from the containing user group.
The userGroupListAll command
generates a list of the names of all currently extant user
groups. The members of an individual group can be displayed using
the userGroupDescribe command.
Access Groups
The omixed security model is based on access control lists. Every item must belong to one access group. The choice of access group determines which users can see, modify or delete the item. Items can be moved from one access group to another at any point, but they must always be in an access group.
There are two special access groups which are always available:
items in the public access group can be seen by everybody, but can only be modified or deleted by the user who owns them.
items in the private access group can only be seen by the user that owns them, all other users will have no idea that the item exists.
The public and private access groups are special in that they are predefined and cannot be modified.
It is possible to create any number of access groups in the spectrum between public and private. Each access group specifies the set of users that can see, modify or delete items in that group.
As an example, imagine a user wanted to be able to create items that were publicly visible (i.e. all users could see them) but that could be edited by either themselves or their colleagues. This could be achieved using the following sequence of commands:
Items placed in the access group created by the above commands will be visible to all users, can be edited by 'freda' and 'frodo' and can be deleted by only by 'freda'.
As the above shows, each access group consists of a number of rules which control who can read, write or delete the items in that access group. The rules can be modified at any time by any user who has sufficient permission to do so.
Note the use above of the special user group 'everybody'. This user group is special in that it is predefined to mean "all users" and cannot be explicitly controlled or modified. Any user created via the userCreate command will automatically become a member of the 'everybody' user group.
A new access group is created using the accessGroupCreate command which takes a single parameter, the name of the new access group. Access group names must be unique, and the special names 'public' and 'private' are not available. Access group names cannot contain any white-space. Although there is no restriction on the length of an access group name, or on the use of punctuation, it is suggested that names are kept reasonably short and simple.
An access group can be permanently deleted using the accessGroupDelete command. It is not possible to delete an access group if any items are currently assigned to it. All items must be moved to a different access group prior to it being deleted.
A new rule is added to an existing access group using the accessGroupAddRule command. The command requires four parameters; the first is the name of the access group, and the subsequent three the specify the rule.
Rules are of the form "allow write Sally", "deny read Bob". Each one has three components; the directive (either 'allow' or 'deny') the action (one of 'read', 'write' or 'delete') and the name of a user or user group to who the rule applies.
Removing a rule from an access group is done with the accessGroupRemoveRule command. This takes four parameters which should be exactly the same as they were to add the rule in the first place.
The accessGroupListAll command generates a list of all of the access groups that have been defined. Note that the special public and private groups will not be included in this list.
The accessGroupDescribe command takes a single parameter identifying an access group and then displays all of the rules associated with that access group. Rules will be displayed in the same format as that used to add them, for instance:
A security policy is a rule which either permits a user (user group) to do something, or prohibits them from doing it.
The simplest example is a rule determining which users can connect to a resource:
The policy grants Freda permission to connect to any resource managed by the server.
Policies typically consist of three parts:
The first component, the directive, is either "allow" or "deny". This determines the final outcome of the policy. When a user attempts to do some activity which is under security policy control, all relevant policies are checked, and the action is only permitted if at least one "allow" condition is met and no "deny" conditions are met. This will be explained in more detail below.
The second part selects the privilege which is governed by the policy, for example "connect" or "resourceSetSchema".
The final component identifies who the policy applies to; i.e. the name of a user or user group.
A global policy (such as the above) is one which applies to all resources (and potentially all user groups and access groups). It is also possible to define more restrictive types of policy which control activities on a specific resource, user group or access group.
The policyAddGlobal command takes three parameters. The first is the directive ( either "allow" or "deny"), the second determines the privilege that is being controlled and the third selects who this policy applies to.
For example, adding the following two policies:
would result in a configuration in which any user can connect to any resource, except for the user 'doris' who cannot connect to anything.
Note the use of the special user group 'everybody' in the above example; this user group is explained here.
The policyAddOnResource command adds a more restrictive kind of policy which only applies to a single resource. It takes four parameters; the first three are the same as for policyAddGlobal and the final one is the name of a resource to which the policy applies. For example, adding the following resource-specific policy:
would mean that user 'nerys' would not be permitted to connect to the resource 'data4' (even though she would be permitted to connect to any other resource because of the "allow connect everybody" policy).
As well as being able to determine who can perform the 'connect' action, the policy mechanism can be used to provide normal users with controlled access to any administration capabilities. For instance, the ability add people to a particular user group can be granted:
The above policy will permit the user 'Frank' to add new members to the user group 'LabUsers'. Note that 'Frank' cannot remove members, as only the permission to use the 'userGroupAddMember' has been granted. The permission is only valid on the user group 'LabUsers'; 'Frank' cannot add members to any other user group. A variant on this policy would be:
which enables any member of the 'LabUsers' group to add new members to the group. Once a new member has been added, that new member will then have permission to add further new members.
Similarly, it is possible to permit users to manipulate resources. For example, if a user has sole use of a resource and wishes to develop their own schemata, it might be sensible to grant them permission to use the 'resourceSetSchema' command:
The user 'mindy' will now have permission to use the 'resourceSetSchema' command on the resource 'expt_alpha'. Note that permission to set the schema is only granted for a specific resource. The user 'mindy' is not permitted to use the command on any other resource.
Permission to call any administration commands can be controlled via policies. By using global policies, normal users can be given a great degree of autonomy without being granted full admin status. For example, a set of users in a user group called 'TrustedUsers' can be permitted to have full control over access groups using the following policies:
Removing a policy is done with a command which exactly mirrors the format of the command which added that policy. So a global policy is removed using the policyRemoveGlobal and a resource-specific policy is removed using policyRemoveOnResource.
The set of policies currently in force can be found using the policyListAll command. This command takes an optional "filter" argument which can be used to filter the resulting policy descriptions based on a regular expression using Java syntax. For example "policyListAll connect" would display a list of policies which are concerned with the 'connect' privilege.
TO DO - complete this section ....
All functionality of the AdminConsole can be accessed from scripting languages by invoking the tool using the -commands or -file command line arguments. The -commands method allows you to provide commands directly as an argument, whilst the -file method permits commands to be read from a file.
The -commands argument takes a single parameter which is a string containing one or more commands specified in the same form as if they were entered by hand. Multiple commands are separated by semicolons. For example:
will attempt to display information about user X and then about user Y.
The -file argument takes a single parameter which is the name of a file containing one or more commands to be executed. Each command should be on a single line in the file, for example:
will create a new user and resource, initialise the resource with a schema and give the new user permission to connect.
If an error occurs during the processing of a series of commands the AdminConsole will terminate without executing any more commands.
If a command which requires one or more parameters is invoked and the parameters are not provided explicitly, then the command will prompt for them interactively. For example:
will prompt for a 'userName' before running the userDescribe command.
The -silent command line option will suppress the display of all unimportant messages, for example the "OK" messages from the server. Only error messages or the output from commands such as userListAll or serverListEvents will be displayed.
The -noexec command line option will cause the AdminConsole to display the commands that would be executed without actually executing them.
Create a new resource called 'foo' and populate it with a schema loaded from a URL (after prompting for the admin password):
Display the server statistics (without displaying any connection details):
Query the server properties to discover the version of the JVM that is being used to run it:
Resources
resourceListAll
display a list of all resources
resourceCreate
create a new resource
resourceGetSchema
retrieve the schema of the named resource into the specified file
resourceSetSchema
install the specified schema into the named resource
resourceUpdateSchema
overwrite the specified schema into the named resource
resourceEmpty
completely remove all data from the named resource
resourceDelete
completely delete the specified resource
resourceBackup
creates a backup file containing all data (and files) in the resource
resourceRestore
restores a resource from backup file (existing data in the resource is lost)
|
Users
userDescribe
display information about a specific user
userListAll
display a list of all users
userCreate
add a new user
userSetPassword
set the password of the specified user
userSetClass
set the class ( 'user', 'guest' or 'manager' ) of the specified user
|
User Groups
userGroupListAll
display a list of all user groups
userGroupCreate
adds a new user group
userGroupDelete
deletes an existing user group
userGroupAddMember
add a user or user group to the named user group
userGroupRemoveMember
remove a user or user group from the named user group
userGroupListMembers
display a list of the members of the named group
|
Access Groups
accessGroupListAll
display a list of all access groups
accessGroupCreate
adds a new access group
accessGroupAddAction
adds a new access rule to an access group
accessGroupRemoveAction
removes one of the access rules from an access group
accessGroupDescribe
displays the rules of the named access group
|
Security Policies
policyListAll
display a list of all policies
policyAddGlobal
add a global policy
policyAddOnResource
add a policy which applies on the named resource
policyAddOnUserGroup
add a policy which applies only to the
named user group
policyAddOnAccessGroup
add a policy which applies only to
the named access group
policyRemoveGlobal
remove a global policy
policyRemoveOnResource
remove a policy which applies on the named resource
policyRemoveOnUsergroup
remove a policy which applies only
to the named user group
policyRemoveOnAccessGroup
remove a policy which applies only
to the named access group
|
Server Statistics and Debug Information
sessionListAll
display a list of the currently active sessions
sessionClose
forcibly closes a specific session
sessionCloseAll
forcibly closes all current sessions
sessionCloseAllOnResource
forceably close all sessions currently open on the named resource
logListAll
display a list of the names of the logs being used
logSetLevel
set the information level of a named log
fileListAll
display all files that have been uploaded to the resource
fileListAllUnused
display all files that have been uploaded to the resource but which are not currently being linked to
fileRemoveAllUnused
removes all files that have been uploaded to the resource but which are not currently being linked to
fileListPerUser
display information about the files that have been uploaded to the resource
lockListAll
display a list of the locks currently in force (and which session they belong to)
lockRevoke
forceably revoke a particular lock
propertyListAll
display a list of the server properties
propertySet
display a list of the server properties
propertyGet
display a list of the server properties
serverDescribe
display information about the server (including the API version)
serverListStatistics
display some server statistics
serverListEvents
display the most recent activities
|
Note that all command line arguments can be abbreviated to their shortest unique prefix, for example -c for -commands or -po for -port.
Provide the host name (or IP address) for the connection. Can be set to [default] to force the use of the default host name (i.e. localhost) without prompting for it.
Provide the network port number for the connection. Can be set to [default] to force the use of the default port number (i.e. 8081) without prompting for it.
Provide the service path for the connection. Can be set to [default] to force the use of the default service path without prompting for it.
Provide the admin password for the connection. Can be set to [default] to force the use of the default password without prompting for it.
Executes one or more commands as provided in the commandString. Multiple commands should be separated by semicolons.
Reads and executes commands from the specified file, one command per line.
Display the list of commands that would be invoked by the -command or -file option without actually executing them.
Suppress the display all unimportant messages. Error messages and the output from certain commands are still displayed.
Enables the debugging mode which displays lots of information detailing the communication between the AdminConsole and the omixed server.