Skip to main content

Using Character-based Security Management Routines

The preferred and recommended way to manage a Caché installation is the Management Portal. The portal provides a convenient, browser-based interface for controlling the system. However, to cover those instances when the system cannot be managed this way, Caché also has several character-based routines that collectively provide many of the same functions on the Terminal.

The utilities described in this appendix are:

  • ^SECURITY — addresses the setup and maintenance of the data essential to the proper functioning of Caché security.

  • ^EncryptionKey — supports operations for encryption key management, database encryption, and data element encryption.

  • ^DATABASE — is used to manage databases; it also allows you to set values related to Caché security.

  • ^%AUDIT — allows the reporting of data from the logs, and the manipulation of entries in the audit logs as well as the logs themselves.

Each of the routines is described in its own section along with its top-level functionality. In most cases, the initial menu choice will lead to further requests for information until the routine has sufficient information to accomplish its task. To use any routine from the Terminal, the user must be in the %SYS namespace and have at least the %Manager role. The routine, for example ^SECURITY, is invoked as expected with the command:


When the routine runs, it presents you with a list of options. Select an option by entering its number after the “Option?” prompt.


As previously noted, the preferred way to manage a Caché system is via the Management Portal. Administrators who elect to use the routines described in this documents are assumed to have a detailed operating knowledge of how Caché works and what parameter values are appropriate for the options they choose.

General notes about prompts

The following are characteristics of prompts when using the character-based facilities:

  • Each option has a numeric prefix. Select an option by typing its number. The option-number pattern is used throughout the routines.

  • All option lists have an item to exit this level of menu and return to the previous level. You may also reply to the “Option?” prompt with Enter. This is interpreted as if you had chosen the “Exit” option, that is, you are finished with that section and you are presented with the next “upper” level of options. An Enter reply to the top-level of options exits the ^SECURITY routine.

  • Many of the prompts for information have a default value which is selected by typing the Enter key. When there is a default value available, it is shown after the prompt message and followed by the characters “=>” as in

    Unsuccessful login attempts before locking user? 5 =>

    where the default value is 5 for the number of times a user may try to login and fail before the system locks their username.

  • Prompts whose defaults are “Yes” or “No” also accept any matching partial response such as “yE” or “n”. The match is done ignoring the case of the response.

  • In options whose intent is to alter the characteristics of existing user, roles, services, and so on, the existing value of the item is displayed as the default. Typing Enter preserves that value and moves on to the next prompt.

  • Some prompts ask for a pattern to use when matching items such as user names. The default pattern is usually “*” that matches all items. In such patterns the asterisk matches any sequence of characters, much like it does in DOS. A pattern may also consist of a comma-separated list of items each of which is treated as its own pattern. An item is treated as being selected if it matches any pattern in the list.


There is nothing to prevent multiple instances of the same routine from being executed at the same time by different system administrators (or even the same administrator). If this happens, it is the responsibility of the administrators to coordinate their activity to avoid conflicts and achieve their objectives with regard to the coherence of the affected data.


This routine addresses the setup and maintenance of the data essential to the proper functioning of Caché security. The initial menu includes:

  1. User setup

    Users represent actual people or other entities who are permitted access to the system. This is the section for define the characteristics of users for the instance.


    User definitions for Caché 2014.1 and later versions are not compatible with user definitions for 2013.1 and previous versions, due to the introduction of the AccountNeverExpires and PasswordNeverExpires fields. If you attempt to import newer definitions into an older version, Caché skips them.

  2. Role setup

    Caché users are given permission to perform an action by their assignment to one or more roles. This section is where the characteristics of roles are defined.

  3. Service setup

    Services control the ability to connect to Caché using various connection technologies. They are predefined by InterSystems. The parameters governing their use are set through this option.

  4. Resource setup

    Resources represent assets, such as databases or applications, whose use is to be managed. A resource may represent a single asset such as a database, or it may protect multiple (usually related) assets such as a suite of applications.

  5. Application setup

    Application definitions serve as proxies for the actual application code. Permissions on the definition are interpreted by the security system as granting the same permission on the application associated with the definition.

  6. Auditing setup

    Auditing is the means by which Caché keeps a record of security-related events. This section deals with the definition and management of events whose occurrence is to be noted in the audit log.

  7. Domain setup

    Domains permit a community of users to be partitioned into several groups. This option allows an administrator to set up Caché security to accept users from multiple domains. The domains defined via this option exist only within the Caché system for the purpose of recognizing valid users. When multiple domains have been defined, usernames should include the domains they will be attempting access from, for example, If a user’s name is given without the domain identification, Caché uses the default domain (if any) set up in the system parameters section.

  8. SSL configuration setup

    SSL/TLS provides authentication and other functionality. This section provides configuration tools if the instance uses Caché support for the SSL/TLS protocol; this includes the use of SSL/TLS with mirroring, such as for creating and editing SSL/TLS configurations for use with mirroring.

  9. Mobile phone service provider setup

    With two-factor authentication, authenticating users receive a one-time security code on their mobile phone that they then enter at a prompt. This section provides the tools for configuring the mobile phone service providers in use for the Caché instance.

  10. OpenAM Identity Services setup

    OpenAM identify services allow Caché to support single-sign on (SSO); by using this feature, users that have already successfully authenticated do not have to re-authenticate. This section deals with managing OpenAM identity services for the Caché instance.

  11. Encryption key setup

    Caché uses keys to encrypt databases or user-specified data elements. This section provides tools for working with keys for both database and managed encryption.

  12. System parameter setup

    The system parameters are a collection of security-related values that apply system-wide. This section includes the ability to export and import all an instance’s security settings, including those for SQL privileges.


    Security information cannot be imported from a different product or a different version of a product.

    Note also:

    • If you are importing security settings from a source instance configured with multiple domains to a target instance not configured to allow multiple domains and the source instance’s default domain differs from that of the target instance, then the import does not update the target’s default domain — you must explicitly set this value. To do this, use the Default security domain drop-down on the System-wide Security Parameters page (System Administration > Security > System Security > System-wide Security Parameters).

    • When importing all security settings, the import/export file includes web application settings; each web application has a Path setting. Before importing settings onto a new drive, VM, or hardware, for each web application, ensure that the value of the Path setting is accurate for that environment. If the web applications associated with the Management Portal do not have correct Path values, the Management Portal will not display correctly.

      To locate the Path setting for each web application in the import/export file (SecurityExport.xml), look in the ApplicationsExport section; in each Applications section, identify the application by the value of the Name setting; then update the value of the Path setting as appropriate.

  13. X509 User setup

    X.509 is the standard for certificates that a public key infrastructure (PKI) uses. Caché uses X.509 certificates for its PKI, and each user associated with an X.509 certificate is known as an X.509 user. This section provides tools for working with X.509 users, such as creating them, editing them, deleting them, and so on.

  14. Exit


The ^EncryptionKey routine is for use with managed key encryption; it supports operations for encryption key management (technology for creation and management of encryption keys and key files), database encryption, and data element encryption.

  1. Create new encryption key and key file

    Allows you to create a new database-encryption key, which it stores in a key file.

  2. Manage existing encryption key file

    Allows you to list administrators associated with a key file, add an administrator to a key file, remove an administrator from a key file, and convert a version 1.0 key file to a version 2.0 key file.

  3. Database encryption

    Allows you to perform encryption management operations, activate a database encryption key, display the unique identifier for the currently activated database encryption key (if there is one), deactivate the activated database encryption key, and configure Caché startup options related to database encryption. Encryption management operations are for converting an unencrypted database to be encrypted, converting an encrypted database to be unencrypted, and converting an encrypted database to use a new key; for more information, see “Performing Encryption Management Operations.”

  4. Data element encryption for applications

    Allows you to activate a data element encryption key, list the unique identifier for any currently activated data element encryption keys (if there are any), and deactivate the activated data element encryption key.


The ^DATABASE routine is used to manage databases; it also allows you to set values related to Caché security.

  1. Create a database

    Allows you to create a new database.

  2. Edit a database

    Allows you to change the characteristics of an existing database, for example, by adding additional volumes.

  3. List databases

    Displays the characteristics of one or more databases.

  4. Delete a database

    Allows you to delete a Caché database. This action is irreversible.

  5. Mount a database

    Makes a database ready for use by Caché. Databases must be mounted to Caché in order to be usable. Databases can be set to be automatically mounted at startup.


    You can use the Mount a database option to mount any CACHE.DAT file accessible to the instance by specifying the directory containing it. However, if you do this with a database that was deleted from, or was never added to, the Management Portal database configuration (see Configuring Databases in the “Configuring Caché” chapter of the Caché System Administration Guide), the database is not added to the Management Portal configuration and is therefore unavailable for portal database operations and for some routines, for example ^Integrity (see Checking Database Integrity Using the ^Integrity Utility in the “Introduction to Data Integrity” chapter of the Caché Data Integrity Guide).

  6. Dismount a database

    Permits you to quiesce a database and remove it from use by Caché.

  7. Compact globals in a database

    Reorganizes the data inside CACHE.DAT. Note that this option does not reduce the size of the database file; to reduce the size of the database, see option 13.

  8. Show free space for a database

    Displays the available space for a database. This is calculated as the difference between its current contents and its current declared size.

  9. Show details for a database

    Displays detailed information on a specified database including location, size, status, and other controlling parameters.

  10. Recreate a database

    Creates a new, empty database with the parameters of the original database. The new database is the same size as the original database.

  11. Manage database encryption

    Removes all the logical data from a database while preserving the properties of the database for reuse.

  12. Return unused space for a database

    Frees either a specified amount of or all available extra space associated with a database, reducing it from its current size to its smallest possible size.

  13. Compact freespace in a database

    Specifies the desired amount of freespace (unused space) that is in a database after the end of the database's data. You can also eliminate this freespace using the Return unused space for a database option (#12).

  14. Defragment globals in a database

    Defragments a database, which organizes its data more efficiently. Defragmentation may leave freespace in a database (see options #12 and #13).


This routine allows the reporting of data from the logs, and the manipulation of entries in the audit logs as well as the logs themselves.

  1. Audit reports

    Permits you to specify selection criteria (date ranges, events, affected users, and so on) and display characteristics, then extracts the data from the audit log and formats it for presentation.

  2. Manage audit logs

    Allows the extraction of log entries to another namespace, the export and import of audit log data to and from external files, and maintenance activities against the audit log itself.

  3. Exit

FeedbackOpens in a new tab