Using the Akula Command-line Management Utility
The Akula Command-line Management Utility lets you configure the Akula Server and app scopes running on the Akula Server. The Akula Command-line provides a simple way to write HTTP requests against the REST endpoints on the Akula Server used to manage app scopes. For a complete list of the REST endpoints, see REST API Reference.
Use the the Akula Command-line to perform administration functions such as the following:
- Configure roles and groups – Create roles, associate permissions with a role, associate user groups with roles, and perform other operations on roles and groups.
- Determine information about a realm – List all groups in a realm and list all realms available to a role.
- Obtain information about the Akula Server or an app scope – Obtain configuration information about the Akula Server, determine which app scopes are enabled, and obtain information about an app scope.
- Start and stop app scopes – Start and stop all app scopes except the server app scope.
- Licensing – Install, update, and delete licenses.
- App properties – Set, update, and reset app properties.
- Logging – Set logging levels on a per-scope basis.
For all three supported platforms, Akula ships the Akula Command-line Management Utility as a Python application. For Microsoft Windows only, Akula ships the Akula Command-line Management Utility as the akula.exe file. For information on installing the Akula Command-line Management Utility, see Install the Akula Command-line Management Utility.
This document describes contains the following sections:
Using the Akula Command-line
To start the Akula Command-line:
- Open a terminal window on your machine.
- Change directory to the directory where the Akula Command-line is located.
- For Microsoft Windows, the default location is the server-sdk/tools/mgmt-util/bin directory in the location where you installed Akula.
- For all other platforms, the default location is the server-sdk/tools/mgmt-util/src directory.
For Microsoft Windows only, if you are using the akula.exe file, invoke the Akula Command-line and include the URL of the Akula Server on invocation, as the following example shows:
For all platforms, use Python to invoke the Akula Command-line from the command line. Include the URL of the Akula Server on invocation, as the following example shows:
akula.pyis the Python file for the Akula Command-line.
Always connect to the URL of the Akula Server itself, not to a specific app scope running on the Akula Server. The Akula Command-line automatically uses the
serverapp scope to perform its management functions.
After you start the Akula Command-line and successfully connect to the Akula Server, you see the Akula Command-line's prompt:
Enter commands to the Akula Command-line at the prompt. For example, enter
helpto see usage information.
If you deployed the default Akula Server configuration files, as described on Set up the Akula Server Environment, then log in to the Akula Server using the default Administrator account:
>login admin admin
Otherwise, you can log in with the credentials defined by your own security realm.
Authorization required to run commands
To use the Akula Command-line, you must first log in. After logging in, the server returns a list of permissions set for your account. You can only run the commands your account is authorized to use. If you run a command you are not authorized to use, the command line interface returns an HTTP 403 error - access forbidden.
For example, if you log in using an account that has only the "
server.View_Roles" permission and then try to run the "
roles server" command you will receive an HTTP 403 error. This is because your account can only view roles, but the "
roles server" command returns permissions, groups, and realms in addition to roles. To run the command successfully, you would need permissions set to view the other three types of data.
Permissions are set either at the scope or server level. At scope level, a user can run commands for which permissions are set, but only on specified app scopes. The permissions set for a user can vary per app scope. At the server level, permissions for a user apply to all apps running on the server. However, if you use the command-line to send a request to a REST endpoint, the endpoint specifies the permissions required for access. For more information, see the REST API Reference.
Editing permissions requires the "
server.Edit_Permissions" setting. The Akula Command-line Utility is shipped with a default administrator account that has that and all other permission settings enabled. To log in to that account, use login:
admin and password:
This section contains examples of commands for the Akula Command-line.
You can obtain help by entering the
help command at the prompt:
The first command that you typically enter is the
login command to log in to the Akula Server.
Most other commands require the user to be authorized to perform administrative actions. Therefore, log in with the credentials of a server admin.
login command has the following syntax:
login principal secret
as the following example shows:
> login firstname.lastname@example.org myPWord
The principal is typically your username, and secret is your password.
If the credentials are correct, the Akula Command-line displays the following message:
Status: Akula Server Version: 2.5.0
List the app scopes
scopes command to see a list of apps running on the Akula Server, as the following example shows:
The output of this command is:
server, App1, and App2 are the names of the apps. The
server app is built in to the Akula Server. App1 and App2 correspond to the names of the AKZ files that represent the apps. For example, App1.akz and App2.akz. For more information on packaging server apps, see Building and Deploying AKZ Files.
Enable or disable an app scope
You can use the Akula Command-line utility to enable or disable an app scope that has been deployed on the Akula Server.
To enable or disable an app scope, use the following command:
> updatescope scope_name [-enabled true|false]
To enable an app scope, set the
enabled flag to
true. To disable an app scope, set the
enabled flag to
The following example enables the MyApp app scope:
> updatescope MyApp -enabled true
If successful, Akula returns an HTTP 200 OK.
If the Akula Server cannot enable or disable an app scope, the server returns one of the following errors:
The following example shows the JSON response for a
If you attempt to enable an app scope that is already enabled, or disable an app scope that is already disabled, Akula returns an HTTP 200 OK.
List the roles, realms, and groups for a server app
Many Akula Command-line commands require you to specify the scope name (corresponding to the app name), a role name, a group name, or a realm name. To determine the roles for a scope, use the command:
> roles App1
Where the argument to the roles command is a scope.
To determine the realms, and user groups in a realm, use:
> realms App1
To determine the groups defined in a realm for a scope, use the command:
> groups App1 MyRealm
Use many of the Akula Command-line commands to modify a role. For example, you can modify a role by:
- Adding, removing, or modifying the role
- Associating groups to a role or disassociating groups from a role
- Associating permissions to a role or disassociating permissions from a role
You can list the roles for an app, as shown below:
Notice how the list of roles is blank.
Add a role to a scope by using the
> addrole App1 newRole
Where newRole is the name of the role.
You can now see the new role:
addgroups command to associate a user group defined in a realm with the role. The name of the group is the unique ID of the group. For example, if you are using Active Directory as your realm, it is a string in the form:
CN=Group Policy Creator Owners,CN=Users,DC=vvod,DC=com
The following example adds a group to the role you created. The realm name in this example is MyRealm:
> addgroups App1 newRole MyRealm "CN=Domain Admins,CN=Users,DC=vvod,DC=com"
You can now see the group in the role:
addpermission command to associate a permission with the role, as the following example shows:
> addpermission App1 newRole ToDo.read
You can now see the permission on the role:
To delete a role, use the
deleterole command, as shown below:
> deleterole App1 newRole
Using a command file
You can write a text file that contains a set of commands to the Akula Command-line, and then run the commands by using the -s option on the command line. The following example runs all the commands in the text file MyCommands.txt using the Microsoft Windows executable version of the Akula Command-line:
akula.exe -s MyCommands.txt
For all platforms, use Python version of the Akula Command-line:
python akula.py -s MyCommands.txt