APX files

This section describes the template files created when you run the apxtool new command. The following table summarizes these files. The sections below describe some of the files in more detail.

APX files

File name	Description
apx.cfg	APX configuration file, contains metadata that fully describes the APX. See The APX configuration file - apx.cfg for more information.
apx.perm	APX permissions file, specifies permission escalation rules. See The APX permissions escalation configuration file - apx.perm for more information.
description.txt	Text description of the APX. Specified with the apxtool new -d option. See Creating a new APX - apxtool new for more information.
interfaces	APX interface definition file. Specifies the interfaces the APX defines or implements. See APX Interfaces - Defining categories of APX Extensions for more information.
usage.txt	Text description of how to use the APX.
run.sh	For program APXs only, this file contains the executable code of the APX. This file contains the functionality of the program APX. For an example, see Tutorial: Creating a program APX for more information.
index.php	For web APXs only, this file contains the PHP source code for the web APX. This file contains the functionality of the web APX. For an example, see Tutorial: Creating a Web Application APX for more information.

The APX configuration file - apx.cfg

All APXs regardless of type must have a configuration file named apx.cfg. The apxtool new command creates a template of this file for you to modify. This file contains metadata that fully describes the APX. The apx.cfg uses a “key=value” format to define the properties of the APX. Multiple lines are joined together with a line continuation character, “\“.

The APX configuration file attributes table describes common attributes for all APXs. APX type specific attributes are described in the corresponding APX type functional specifications. Note that some of the attributes may be extracted from the apx.cfg configuration file and managed in SA. For modifiable attributes such as the description, subsequent updates of the apx.cfg file will update the SA managed data accordingly.

To see an example apx.cfg file, run the apxtool new command and open the files it creates.

APX configuration file attributes

Attribute	Modifiable?	Description
type	No	The type of the APX, which must be either webapp or script. (Script APXs are also known as Program APXs.) Once created, you cannot change the APX type.
name	Yes	This is the APX display name and may contain multi-byte characters. This name can be changed at any time. This name will be listed in the SA Client APX folders.
unique_name	No	The unique name of the APX. This name will be used as the file name for the APX as it appears in the OGFS. This name together with the type forms a key that uniquely identifies an APX. Once created, the name cannot be changed. Since this name is used in the file system, it must conform to the file system naming specification. Generally, this name should be in ASCII.
version	Yes	The version string representing the current version of the APX. If the value begins with the string “auto:”, then SA will automatically manage the versions using an integer incremented for each new version.
description	Yes	A text description of what the APX does. You can alternatively use the file description.txt instead of this attribute.
usage	Yes	A text description describing how to use the APX. You can alternatively use the file usage.txt instead of this attribute.
interfaces	Yes	One or more interfaces the APX implements. Separate multiple interfaces with a colon (:) character.
command	Yes	The executable file the APX is to run when it is invoked.

 

The APX permissions escalation configuration file - apx.perm

Use the file apx.perm to specify permission escalation rules. If this file does not exist, or if it contains no escalation permissions, the APX will run with the user's default permissions.

When a new APX is created using the APX Tool’s New command, it generates certain default files, including a default apx.perm file, which by default has no escalation permissions defined. The default file does contain some commented out examples which an APX developer can use as templates.

There are three ways to specify escalations, described below.

• No escalation
• All permissions
• With escalation

No escalation

The escalations attribute is not specified. The APX runtime uses the current user privilege to execute an APX. If an APX invokes privileged operation which a user does not have, APX execution will terminate with an error.

All permissions

This is a special privilege that temporarily grants all operation permissions to a user. It is intended for development or demo use only. This is a useful tool for speedy proof of concept, or demo, without worrying fine grain permission tuning. It is a poor choice for a production environment due to its lack of security.

To grant all permissions, edit file apx.perm with a macro that matches all features with wildcard characters. For example:

use_feature(name=”*”)

With escalation

Specify a list of predefined common operations in the apx.perm file. When executing the APX, the APX runtime temporarily grants these permissions to the APX. SA has a comprehensive list of feature and resource permissions. To simplify the task of escalating related feature, one can use wildcard characters to match groups of related features. For example:

@use_feature(name=”Application.*”)