ttInstanceCreate

The ttInstanceCreate utility creates a new TimesTen instance.

Required Privilege

Run this utility as the instance administrator.

Syntax

% ttInstanceCreate -h
ttInstanceCreate - Creates a new instance

Usage:

  ttInstanceCreate [common_options] [server_options] [classic_options]

    Creates a classic instance

  ttInstanceCreate [common_options] -clientonly

    Creates a Client-Only instance

common_options:

  -name <instance_name> Specifies the target instance name
  -location <path>      Specifies the target instance directory
  -force                Removes any existing instance in <location> without confirmation
  -record <file>        Creates instance and records prompt responses to the given file
  -batch <file>         Reads answers for prompted questions from the given file
  -strict               Prevents instance creation on unsupported platforms
  -tnsadmin <path>      Specifies the path for the TNS_ADMIN environment variable
  -verbose              Displays extra information
  -help|h               Displays this help message and exits
  -clientonly           Creates a client instance
  -ssl_fips_140         Enables SSL (TLS) FIPS encryption for both client and server
  -db_fips_140          Enables FIPS symmetric encryption (TDE) for both client and server

server_options:

  -nostart              Do not start the daemon (even in interactive mode)
  -daemonport <port>    The port on which the daemon of the created instance will listen
  -csport <port>        The port on which the C/S server of the created instance will listen
  -systemd              Enable systemd
  -serverencryption <requirement>   Whether C/S traffic is encrypted. 
  -asym_alg <algorithm> Asymmetric algorithm for certificate generation: ECC, RSA
  -serverciphersuites <suites>      Cipher suites used for TLS encryption. One of, or a comma-separated list of:
                        TLS_AES_128_CCM_SHA256  (FIPS=yes, ECC=yes, RSA=yes)
                        TLS_AES_128_GCM_SHA256  (FIPS=yes, ECC=yes, RSA=yes)
                        TLS_AES_256_GCM_SHA384  (FIPS=yes, ECC=yes, RSA=yes)
                        TLS_CHACHA20_POLY1305_SHA256    (FIPS=no , ECC=yes, RSA=yes)
                        TLS_DHE_RSA_WITH_AES_128_GCM_SHA256     (FIPS=yes, ECC=no , RSA=yes)
                        TLS_DHE_RSA_WITH_AES_256_GCM_SHA384     (FIPS=yes, ECC=no , RSA=yes)
                        TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (FIPS=yes, ECC=yes, RSA=no )
                        TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 (FIPS=yes, ECC=yes, RSA=no )
                        TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   (FIPS=yes, ECC=no , RSA=yes)
                        TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   (FIPS=yes, ECC=no , RSA=yes)
classic_options:

  -start               Starts the daemon after instance creation (default when running this tool in interactive mode)

Options

ttInstanceCreate has the following options:

Option Description
Common options:

-h

-help

-?

Displays help information.

-name name

Specifies the name of the instance to be created.

-location path

Specifies the directory path where the instance is created. This directory must already exist. A new directory is created in the existing directory. The name of the new directory is specified in the -name option. This new directory is the new instance home.

-force

Specifies that an instance directory specified with the -force option is to be overwritten if it already exists. The directory is overwritten only if:

  • The specified instance directory is empty, or
  • The specified instance directory contains a conf/timesten.conf file.

-record filename

Records responses to installation questions into the file specified by filename. The file then can be specified as the parameter to the -batch option.

-batch [filename]

Specifies the file to be used to provide input to the ttInstanceCreate utility. If not specified, no input file is used.

-strict

Ensures that the platform running the command is supported and prevents the instance creation if it is not.

-tnsadmin path

For cache operations, this option configures the location to be used for the TNS_ADMIN setting.

-verbose

Displays additional information during the operation of the utility.

-clientonly

Specifies that the instance is client-only.

-ssl_fips_140 Enables SSL (TLS) FIPS encryption for both client and server.
-db_fips_140 Enables FIPS symmetric encryption (TDE) for both client and server.
Server options:
-nostart Do not start the daemon.

-daemonport port

The port number on which the TimesTen daemon process (timestend) for this instance listens. This port must not already be in use by any other application or instance on the system.

-csport port

The value to be used for the TimesTen client/server port number for this instance. If not specified, the default is daemonport + 1.

-systemd

Specifies that the instance’s main daemon will be managed by systemd.
-serverEncryption requirement

Determines whether encryption is accepted, rejected, requested, or required for a client/server connection.

  • accepted: Enable an encrypted session if required or requested by the client; use an unencrypted session otherwise. This is the default.
  • rejected: Demand an unencrypted session. (If the server does not support encryption, TimesTen behaves as if this is the setting on the server.) The connection is rejected if the client requires encryption.
  • requested: Request an encrypted session if the client allows it (if the client has any setting other than rejected); use an unencrypted session otherwise.
  • required: Demand an encrypted session. Reject the connection if the client rejects encryption.

With a setting other than rejected, the ttInstanceCreate utility generates certificates for TLS if there are compatible settings for server encryption between the server and client (as long as there are also compatible settings for cipher suites). See Transport Layer Security for TimesTen Client/Server in Oracle TimesTen In-Memory Database Security Guide.

The -serverEncryption and -serverCipherSuites values are set at the instance creation level in the timesten.conf file and serve as the default values for any database created on that instance. However, you can override them by setting the corresponding connection attribute in the database definition.

Note: If you did not create certificates when you created the instance, you need to run the ttCreateCerts utility manually to use TLS on a particular database.

-asym_alg ECC|RSA

Specifies the asymmetric cryptographic algorithm to use when generating a key pair for TLS. The valid values are ECC or RSA. The ttCreateInstance utility passes the -asym_alg option to the ttCreateCerts utility. See ttCreateCerts.

The -asym_alg option is optional. If you do specify it, ensure that the algorithm you choose matches the cipher suites you choose. For example, if you specify RSA, ensure your list of cipher suites include one or more RSA-specific cipher suites.

If you do not specify -asym_alg, TimesTen does the following:

  • Checks to see which of the algorithms (ECC or RSA) is common to the given cipher suites, and uses that one.

  • If both ECC and RSA are commonly used, TimesTen uses ECC.

  • If there is no common algorithm, TimesTen generates an error.
-serverCipherSuites {suites}

Lists the cipher suite or cipher suites that can be used for Transport Layer Security, depending also on the client setting. There is no default setting. Specify one or more TLS version 1.3 or 1.2 cipher suites in a comma-separated list from strongest to weakest. To use TLS, the server and client settings must include at least one common suite. See Cipher Suites in TimesTen in Oracle TimesTen In-Memory Database Security Guide to learn more about the supported cipher suites and how TimesTen negotiates cipher suite selection.

For more information on TLS for encrypted communication between clients and server, see Transport Layer Security for TimesTen Client/Server in Oracle TimesTen In-Memory Database Security Guide.

Classic options:

-start

Specifies that the instance should be started after it is created.

You can specify options in one of these ways:

  • On the command line

  • In a file

  • Interactively as the utility runs

If you do not specify options on the command line, or if the only options used are -record and/or -verbose, ttInstanceCreate runs in an interactive mode, prompting the Instance Administrator for the information needed to create the instance.

If you specify the -batch option on the command line, ttInstanceCreate runs in interactive mode, and attempts to answer any questions by fetching the answers from a recorded batch file, generated by a previous run that specified the -record option. If the answer to a question is not present in the batch file, the utility prompts the Instance Administrator to answer the question interactively.

If you specify other options on the command line, they are used as the source of information. The ttInstanceCreate utility does not prompt the user for unknown values.

Examples

This example shows how a new TimesTen client only instance named testclient in the /scratch/mylocation location is created.
% ttInstanceCreate -name testclient -location /scratch/myinstance -clientonly
Creating instance in /scratch/myinstance/testclient ...
The 26.1 Release Notes are located here :
  '/scratch/newinstall/tt26.1.1.1.0/README.html'

Instance created successfully.
In this example, the utility creates an instance named test112 in the /scratch/mylocation location with the specified cipher suite TLS_AES_128_CCM_SHA256. It generates the ECC key for the cipher suite TLS_AES_128_CCM_SHA256.
% ttInstanceCreate -name test112 -location /scratch/mylocation -serverEncryption accepted -serverciphersuites TLS_AES_128_CCM_SHA256
Creating instance in /scratch/mylocation/test112 ...
INFO: Creating certificates, this may take some time ...
ttCreateCerts : certificates created in /scratch/mylocation/test112/conf

NOTE: The TimesTen daemon startup/shutdown scripts have not been installed.

The startup script is located here :
        '/scratch/mylocation/test112/startup/tt_test112'

Run the 'setuproot' script :
        /scratch/mylocation/test112/bin/setuproot -install
This will move the TimesTen startup script into its appropriate location.

The 26.1 Release Notes are located here :
  '/scratch/mylocation/newinstall/tt26.1.1.1.0/README.html'

Instance created successfully.

In this example, ttInstanceCreate generates the RSA key for encryption at the instance level. 

% ttInstanceCreate -name test121 -location /scratch/mylocation -serverEncryption accepted -serverciphersuites TLS_AES_128_CCM_SHA256 -asym_alg RSA
Creating instance in /scratch/mylocation/test121 ...
INFO: Creating certificates, this may take some time ...
ttCreateCerts : certificates created in /scratch/mylocation/test121/conf

NOTE: The TimesTen daemon startup/shutdown scripts have not been installed.

The startup script is located here :
        '/scratch/mylocation/test121/startup/tt_test121'

Run the 'setuproot' script :
        /scratch/mylocation/test121/bin/setuproot -install
This will move the TimesTen startup script into its appropriate location.

The 26.1 Release Notes are located here :
  '/scratch/mylocation/newinstall/tt26.1.1.1.0/README.html'

Instance created successfully.

This example shows that the asymmetric algorithm ECC is not compatible with the TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 cipher suite. 

% ttInstanceCreate -name test12 -location /scratch/mylocation -serverEncryption accepted -serverciphersuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 -asym_alg ECC
ERROR: Requested asymmetric algorithm 'ECC' not compatible with all the given cipher suites.
Failed to create instance.

This example shows when a compatible cipher suite that resolves to RSA is passed. 

% ttInstanceCreate -name test12 -location /scratch/mylocation -serverEncryption accepted -serverciphersuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384 
[...] 
Will use asym_alg 'RSA'