mfsecconv Command Reference

mfsecconv sub-command parameters [options]

Administer security definitions for the VSAM ESM Module.

Sub-commands

init

Initialize the default Enterprise Server security configuration. This sub-command will only make changes to the system if there is currently no VSAM ESM Module security data in the default location, which is %ProgramData%\Micro Focus\product-name\vsam_esm (Windows) or $COBDIR/etc/config/vsam_esm (UNIX).

reset

Equivalent to the init sub-command, except that it will overwrite any existing security configuration in the default location. It will also overwrite any entries in the default Micro Focus Secrets Vault used by the default Enterprise Server security configuration, microfocus/temp/admin and microfocus/common/readonly (possibly affected by options specified on the command).

import

Import security definitions from a YAML or LDIF file into a set of VSAM (COBOL indexed) data files for the VSAM ESM Module. Options specify whether existing definitions will be replaced, updated, or left unchanged, and whether new definitions will be added.
Convert security definitions in an LDIF file into YAML format.

export

Create a YAML file containing the security definitions from a set of VSAM ESM Module data files.

init and reset

Syntax:

```
mfsecconv init [options]
```

or:

```
mfsecconv reset [options]
```

These sub-commands create the security definitions for the default Enterprise Server security configuration, and (by default) put user account credentials in the vault. The only difference between init and reset is that init will not overwrite existing security data, and reset will. mfsecconv init is run by the product installer to create the default Enterprise Server security configuration when the product is installed.

Note: These commands only update the VSAM ESM Module security data (in the default location) and information in the vault. They do not change the security definitions in ESCWA or MFDS. See To Recreate the Default Enterprise Server Security Configuration if you need to restore the full default configuration.

CAUTION:

Micro Focus recommends that you back up your existing security data prior to running the mfsecconv reset command.

Options for init and reset

-h|-H|--help: Displays the command help.
-s|-S|--user username: Add username as an administrator to the security definitions. This can be used multiple times. If at least one instance of this option is used, the SYSAD default administrator will not be installed, unless it is also specified with this option, that is --user SYSAD is specified. Unless a password is also supplied with the --pass option or one of its aliases, a random password will be generated for the user and stored in the list of credentials in the vault under microfocus/temp/admin.
-p|-P|--pass password: Set the password for the previous user account, specified with --user. If no password is supplied for a user, a random one will be generated, as described for --user.
-d|-D|--displaypass: Rather than writing generated credentials to the vault, write them to standard output.
-i|-I|--interactive: Rather than generating passwords, read them from standard input.
-x|-X|--exit-codes: Typically, mfsecconv exits with an exit code of 0 if no error messages were logged, that is, nothing more severe than a warning. If the --exit-codes option is specified, it exits with a return code of 3 if there was a fatal (critical) error, 2 if there were any non-fatal errors, 1 if there were any warnings, or 0 if there were no warnings or errors. This might be useful when invoking mfsecconv from a script.

For example:

mfsecconv reset --user MYADMIN --pass Secret_1

import

Syntax:

mfsecconv import source-file destination [options]

source-file: This is a YAML or LDIF file. It must have one of the following extensions .yaml, .yml, .ldif, or .ldf and is case insensitive.
destination: This is either a directory where VSAM files will be created, or a YAML file, which must have an extension of .yaml or .yml.

This sub-command either generates VSAM ESM Module security data from a YAML or LDIF file, or converts an LDIF file containing security data (using the Micro Focus LDAP schema) to YAML. It can be used to generate the VSAM security data for first use, for example to install a stock security configuration on a new system or initialize security for an enterprise server instance running in a container, to update existing security data with new or modified definitions, to migrate from LDAP-based security to VSAM-based, and so on.

When importing to VSAM, there are three options which control how the new data interacts with any existing security data: --truncate, --update, and --append. Either one or two of these needs to be specified for the command to have an effect. The options and their affect are as follows:

--truncate: Any existing security data is deleted. The target directory is created if necessary.
--append: New records are added to the existing security data, where the imported information does not conflict with the existing data. Information in the source which matches an existing record is ignored.
--update: Existing data is updated where the imported information refers to an existing record. Information in the source which does not correspond to an existing record is ignored.
--truncate --append: Any existing data is deleted, the directory is created if necessary, and the source information is used to create the security data.
--append --update: No existing data is deleted. Information in the source that matches an existing record updates the existing record; new records are created for new information in the source.

Note: When using the --update option, ensure the file you are importing does not contain definitions for any objects in the existing security configuration that you do not wish to change. Specifically, avoid using --update with es_default_security.yaml, as you will overwrite any changes that have been made to your security configuration, including the password generated for the SYSAD user during product installation.

Options for import:

-h|-H|--help: Displays the command help.
-a|-A|--append: Imported information which does not match an existing record will be added.
-t|-T|--truncate: Delete existing security data.
-u|-U|--update: Imported information which matches an existing record will update that record.
-l|-L|--loglevel value: Set the logging verbosity. value is an integer 0-4, with higher numbers suppressing more messages. Level 1 suppresses debug messages, level 2 also suppresses informational messages, level 3 also suppresses warning messages, and level 4 also suppresses non-fatal error messages, only critical errors are displayed.

For example:

mfsecconv import security_defs.yaml $COBDIR/etc/vsam_esm --append --update

The VSAM ESM file directory structure will be similar to the following:

$COBDIR/etc/vsam_esm
|---Users.dat
|---PasswordHistories.dat
|---Groups.dat
|---Memberships.dat
|---Classes.dat
|---ACICSPCT # A resource class name
|---|---ACEs.dat
|---|---Rules.dat
|---CCICSCMD # Another resource class name
|---|---ACEs.dat
|---|---Rules.dat

export

Syntax:

mfsecconv export source destination-file [options]

source: This is a directory containing VSAM ESM Module security data files.
destination: This is a YAML file, which must have an extension of .yaml or .yml, and is case insensitive.

This subcommand creates a YAML file representing the VSAM ESM security data in the source directory. This can be used to back up or replicate the security configuration, or create a text version which can be edited and then imported back into the security data files.

Options for export:

-h|-H|--help: Displays the command help.
-l|-L|--loglevel value: This sets the logging verbosity. value is an integer 0-4, with higher numbers suppressing more messages. Level 1 suppresses debug messages, level 2 also suppresses informational messages, level 3 also suppresses warning messages, and level 4 also suppresses non-fatal error messages, only critical errors are displayed.

For example:

mfsecconv export "c:\ProgramData\Micro Focus\Enterprise Developer\vsam_esm" c:\secdefs.yaml