The <class>SYS.Container</class> class contains methods to help users run IRIS inside an OCI-compliant container. More...

Inheritance diagram for Container:

[legend]

Collaboration diagram for Container:

[legend]

Static Public Member Functions
_.Library.Status	ChangeGatewayMgrPassword (_.Library.String pPasswordFile, _.Library.String pCSPIniFile)
	The <class>SYS.Container</class> class contains methods to help users run IRIS inside an OCI-compliant container. More...

_.Library.Status	ChangePassword (_.Library.String pPasswordFile)
	Change the password of all enabled accounts with changeable passwords, and a. More...

_.Library.Status	EnableOSAuthentication ()
	Enables Operating-System-Based Authentication for this instance. More...

_.Library.Status	ErrorHandler (_.Library.Status pSC)
	Takes a Status object as input. More...

_.Library.Status	ForcePasswordChange ()
	This method forces all IRIS users for this instance to change their password. More...

_.Library.Status	KillPassword (_.Library.String pUsername)
	Removes the IRIS password for a user. More...

_.Library.Status	LockDownInstance ()
	Performs additional securing of this instance. More...

_.Library.Status	PreventFailoverMessage ()
	IRIS stores the hostname it is running on in the database. More...

_.Library.Status	PreventJournalRolloverMessage ()
	This method prevents messages from journal rollover in freshly-started. More...

_.Library.Status	QuiesceForBundling ()
	This method runs all of the ObjectScript code necessary to get. More...

_.Library.Status	SetMonitorStateOK ()
	Clears severity 1 and severity 2 alerts from the System Monitor. More...

_.Library.Status	SetNeverExpires (_.Library.String pUsername)
	Sets the AccountNeverExpires bit for a username. More...

Static Private Member Functions
_.Library.Status	__ReadPasswordFile (_.Library.String pPasswordFile, _.Library.String pPassword)
	Reads the first line of text of a file into pPassword. More...

Detailed Description

The <class>SYS.Container</class> class contains methods to help users run IRIS inside an OCI-compliant container.

The primary use case for these methods is to be called during the process of building an IRIS image, and these methods are called during InterSystems' own image build process.

This class is designed to "fail loudly" to minimize the chance of uncaught errors in an image build process. By default, all public methods in <class>SYS.Container</class> will print any error to the console and terminate the entire calling process with an exit status of 1, which makes it easier to detect failures in automated build environments.

This behavior can be controlled by calling processes through environment variables, as specified in the documentation for <method>ErrorHandler()</method>.

InterSystems builds official IRIS images using <method>QuiesceForBundling()</method>.

Member Function Documentation

◆ ChangeGatewayMgrPassword()

_.Library.Status ChangeGatewayMgrPassword	(	_.Library.String	pPasswordFile,
		_.Library.String	pCSPIniFile
	)

static

The <class>SYS.Container</class> class contains methods to help users run IRIS inside an OCI-compliant container.

The primary use case for these methods is to be called during the process of building an IRIS image, and these methods are called during InterSystems' own image build process.

This class is designed to "fail loudly" to minimize the chance of uncaught errors in an image build process. By default, all public methods in <class>SYS.Container</class> will print any error to the console and terminate the entire calling process with an exit status of 1, which makes it easier to detect failures in automated build environments.

This behavior can be controlled by calling processes through environment variables, as specified in the documentation for <method>ErrorHandler()</method>.

InterSystems builds official IRIS images using <method>QuiesceForBundling()</method>.

Changes the Gateway Manager password in CSP.ini.

pPasswordFile Absolute path to file whose first line is our new cleartext password.

pCSPIniFile Override for path to CSP.ini file. It is usually correct to leave this blank and use the default.

◆ ChangePassword()

_.Library.Status ChangePassword ( _.Library.String pPasswordFile )

static

Change the password of all enabled accounts with changeable passwords, and a.

non-empty role or the special user CSPSystem. This method takes a cleartext file as input, and IRIS encrypts the contents appropriately.

pPasswordFile Absolute path to file whose first line is our new cleartext password.

◆ EnableOSAuthentication()

_.Library.Status EnableOSAuthentication ( )

static

Enables Operating-System-Based Authentication for this instance.

This

streamlines automation tasks common in containers. For more, see OS Authentication.

◆ ErrorHandler()

_.Library.Status ErrorHandler ( _.Library.Status pSC )

static

Takes a Status object as input.

Returns that value or "fails loudly"

by printing the error text and terminating the process, exit status 1.

These behaviors can be suppressed by setting either SYS_CONTAINER_QUIET or SYS_CONTAINER_CONTINUE_ON_ERROR to 1 in the OS environment.

Setting both makes this function a no-op.

pSC The Status object to be interpreted.

◆ ForcePasswordChange()

_.Library.Status ForcePasswordChange ( )

static

This method forces all IRIS users for this instance to change their password.

as part of their next login. The special user CSPSystem is excluded.

◆ KillPassword()

_.Library.Status KillPassword ( _.Library.String pUsername )

static

Removes the IRIS password for a user.

This destroys the ability to login via

any authentication which requires a password. Non-password forms, such as OS-based authentication, will continue to work.

pUsername The IRIS username to be operated on.

◆ LockDownInstance()

_.Library.Status LockDownInstance ( )

static

Performs additional securing of this instance.

The instance must have been

installed with GCI_prepare_install::GCI_security_initial"Locked Down" security settings. Some of these changes may be inconvenient for development or other interactive use cases, but they may be useful for running IRIS containers in production.

The steps taken by this method are a suggestion. No one set of security settings will be perfect for all use cases and customers are strongly encouraged to examine their use case and make the best decisions available.

◆ PreventFailoverMessage()

_.Library.Status PreventFailoverMessage ( )

static

IRIS stores the hostname it is running on in the database.

If IRIS later

starts and discovers the hostname has changed, it will emit a warning: "System appears to have failed over from node <var>OLD_HOSTNAME</var>". This method removes the stored hostname, preventing that message.

Container healthchecks are based on the System Monitor state. If this failover message is not suppressed, a new container may spend its first several minutes with the System Monitor in a "warn" state, which will cause container healthchecks to fail.

◆ PreventJournalRolloverMessage()

_.Library.Status PreventJournalRolloverMessage ( )

static

This method prevents messages from journal rollover in freshly-started.

containers. It is not guaranteed to work if the instance is not started with "nostu", as the normal shutdown process involves recording journaling metadata.

For more about "nostu", see Controlling an InterSystems IRIS Instance.

◆ QuiesceForBundling()

_.Library.Status QuiesceForBundling ( )

static

This method runs all of the ObjectScript code necessary to get.

InterSystems IRIS into a state where it can safely be serialized into a container image.

Customers who build their own images are not required to implement this method exactly, but might find the source to be a useful starting point.

◆ __ReadPasswordFile()

_.Library.Status __ReadPasswordFile	(	_.Library.String	pPasswordFile,
		_.Library.String	pPassword
	)

staticprivate

Reads the first line of text of a file into pPassword.

Intended for reading

password files, but could be used for other purposes. Fails if the file does not exist or the first line is empty.

pPasswordFile Absolute path to file whose first line is our new cleartext password.

pPassword Passed by reference, set to be the first line of pPasswordFile, minus newline.

◆ SetMonitorStateOK()

_.Library.Status SetMonitorStateOK ( )

static

Clears severity 1 and severity 2 alerts from the System Monitor.

These

messages are usually transient and inappropriate to have in an instance which is being quiesced into an image.

If there have been any severity 3 alerts, this method will return an error, as severity 3 messages are fatal and indicate that this instance should not be made into an image at all.

For more information on the System Monitor and severity levels, see System Monitor Status and Resource Metrics.

◆ SetNeverExpires()

_.Library.Status SetNeverExpires ( _.Library.String pUsername )

static

Sets the AccountNeverExpires bit for a username.

Without this, user

accounts will expire in images that are more than 90 days old. For more, see Security Management.

pUsername The IRIS username to be operated on.

Static Public Member Functions

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ ChangeGatewayMgrPassword()

◆ ChangePassword()

◆ EnableOSAuthentication()

◆ ErrorHandler()

◆ ForcePasswordChange()

◆ KillPassword()

◆ LockDownInstance()

◆ PreventFailoverMessage()

◆ PreventJournalRolloverMessage()

◆ QuiesceForBundling()

◆ __ReadPasswordFile()

◆ SetMonitorStateOK()

◆ SetNeverExpires()