freem/doc/fmadm.8 - view

File: [Coherent Logic Development] / freem / doc / fmadm.8
Revision 1.5: download - view: text, annotated - select for diffs
Fri Apr 18 01:23:05 2025 UTC (2 days, 2 hours ago) by snw
Branches: MAIN
CVS tags: HEAD

More documentation updates

.\" To display this man page, either: .\" 1) Install this file along with the other subject.8 files in your .\" system's man1 directory (usually this is /usr/man/man18) and .\" enter the command: .\" man fmadm .\" or .\" 2) Specify the input (this file) and the output (your favorite pager) .\" explicitly. For example, if this file is in your current working .\" directory, you can use the following to view the formatted man page .\" using the "less" pager: .\" man ./fmadm.8 | less .\" .\" To print this man page to a PostScript printer: .\" man -t ./fmadm.8 | lpr .\" .\" $Id: fmadm.8,v 1.5 2025/04/18 01:23:05 snw Exp $ .\" fmadm man page .\" .\" .\" Author: Serena Willis <snw@coherent-logic.com> .\" Copyright (C) 2025 Coherent Logic Development LLC .\" .\" .\" This file is part of FreeM. .\" .\" FreeM is free software: you can redistribute it and/or modify .\" it under the terms of the GNU Affero Public License as published by .\" the Free Software Foundation, either version 3 of the License, or .\" (at your option) any later version. .\" .\" FreeM is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU Affero Public License for more details. .\" .\" You should have received a copy of the GNU Affero Public License .\" along with FreeM. If not, see <https://www.gnu.org/licenses/>. .\" .\" $Log: fmadm.8,v $ .\" Revision 1.5 2025/04/18 01:23:05 snw .\" More documentation updates .\" .\" Revision 1.4 2025/04/17 17:57:35 snw .\" Major updates to man pages .\" .\" Revision 1.3 2025/04/17 15:08:24 snw .\" Add documentation on FREEM_LOG_THRESHOLD environment variables to man pages .\" .\" Revision 1.2 2025/04/04 12:49:19 snw .\" Dollar signs cut off in ENVIRONMENT sections of both man pages .\" .\" Revision 1.1 2025/04/03 15:56:41 snw .\" Add fmadm man page to CVS .\" .\" .TH fmadm 8 "3 April 2025" FreeM "FreeM User Manual" .SH NAME fmadm .SH SYNOPSIS fmadm <action> <object> [-e=<environment] [-n=<namespace>] [OPTIONS] fmadm configure [-e=<environment] [-n=<namespace>] [-u=<user>] [-g=<group>] [-E=true|false] fmadm reconfigure [-e=<environment] [-n=<namespace>] [-u=<user>] [-g=<group>] [-E=true|false] <action> can be one of: list, examine, verify, remove, import, export, backup, restore, edit, start, stop, restart, status <object> can be one of: lock, journal, namespace, global, routine, job, environment Running fmadm with no command-line arguments will start the interactive mode. .SH DESCRIPTION The .B fmadm program is a systems administration tool used by FreeM operators to manage their environments. Please see the FreeM texinfo documentation for more details ("info freem"). .SH FLAGS Please note that fmadm flags MUST consist of a hyphen, the letter representing the flag, an equal sign, and the value for the flag. A valid flag looks like this: \-e=DEFAULT Spaces surrounding the equal sign, or a space in lieu of the equal sign, are invalid syntax. .TP \-e .RS 4 Sets the environment to be acted upon in this fmadm session. \fIDEFAULT\fR is assumed if this flag is not provided. .RE .TP \-n .RS 4 Sets the namespace to be acted upon in this fmadm session. \fISYSTEM\fR is assumed if this flag is not provided. .RE .TP \-u .RS 4 Sets the owning UNIX account of the environment. \fIfreem\fR is assumed if this flag is not provided. The UNIX account must already exist on your system. Applies only to \fIfmadm configure\fR and \fIfmadm reconfigure\fR. .RE .TP \-g .RS 4 Sets the owning UNIX group of the environment. \fIfreem\fR is assumed if this flag is not provided. The UNIX group must already exist on your system. Applies only to \fIfmadm configure\fR and \fIfmadm reconfigure\fR. .RE .TP \-E .RS 4 Enables or disables an environment. Valid values are \fItrue\fR and \fIfalse\fR. \fItrue\fR is assumed if this flag is not provided. Applies only to \fIfmadm configure\fR and \fIfmadm reconfigure\fR. .RE .SH ACTIONS .TP configure .RS 4 Configures an environment. No object will be used with this action. Instead, the \fI-e\fR, \fI-u\fR, \fI-g\fR, and \fI-E\fR flags will be referenced. .RE .TP reconfigure .RS 4 Reconfigures an environment. No object will be used with this action. Instead, the \fI-e\fR, \fI-u\fR, \fI-g\fR, and \fI-E\fR flags will be referenced. .RE .TP list .RS 4 Generates a list of <object>s. Applies to \fIlock\fR, \fIroutine\fR, \fIglobal\fR, and job. .RE .TP examine .RS 4 Examines a specific instance of \fI<object>\fR. Applies to \fIroutine\fR, \fIglobal\fR, \fIjob\fR, and \fIjournal\fR. .RE .TP verify .RS 4 Verifies the integrity of \fI<object>\fR. Applies to \fIglobal\fR. .RE .TP remove .RS 4 Removes an instance of \fI<object>\fR. Applies to \fIjob\fR, \fIlock\fR, \fIroutine\fR, and \fIglobal\fR. .RE .TP import .RS 4 Imports an instance of \fI<object>\fR. Applies to \fIroutine\fR (imports routine archives in RO/RSA format). .RE .TP export .RS 4 Exports an instance of \fI<object>\fR. Applies to \fIroutine\fR (exports routine archives in RO/RSA format). .RE .TP backup .RS 4 Backs up an instance of \fI<object>\fR. Applies to \fIroutine\fR. .RE .TP restore .RS 4 Restores an instance of \fI<object>\fR. Applies to \fIjournal\fR (plays back after-image journals). .RE .TP edit .RS 4 Edits an \fI<object>\fR. Applies to \fIroutine\fR (will open the routine in \fI$EDITOR\fR) and \fIglobal\fR (will open the interactive global editor). .RE .TP start .RS 4 Starts one environment, multiple environments, or all environments. Applies to \fIenvironment\fR. .RE .TP stop .RS 4 Stops one environment, multiple environments, or all environments. Applies to \fIenvironment\fR. .RE .TP restart .RS 4 Restarts one environment, multiple environments, or all environments. Applies to \fIenvironment\fR. .RE .TP status .RS 4 Gets the status of one environment, multiple environments, or all environments. Applies to \fIenvironment\fR. .RE .SH "FURTHER INFORMATION" Please note that the primary documentation for FreeM is the 'info' manual, accessed with the following command: \fIinfo freem\fR These manual pages are minimal, and maintained on a strictly best-effort basis. .SH "RETURN VALUES" Returns 0 for non-error condition. .SH FILES .TP env.conf .RS 4 The FreeM environment catalog. Normally located in $PREFIX/etc/freem/env.conf .RE .TP freem.conf .RS 4 The FreeM configuration file. Normally located in $PREFIX/etc/freem/<environment-name>/freem.conf. .RE .SH ENVIRONMENT .TP $EDITOR .RS 4 Determines the text editor used by \fIedit routine\fR. .RE .TP $FREEM_LOG_THRESHOLD_FILE .RS 4 Overrides the configured threshold at which log messages are written to files in \fI/var/log/freem\fR, corresponding to the \fIlog_threshold_file\fR environment setting in \fI$PREFIX/etc/env.conf\fR. The default value is \fIinfo\fR. .RE .TP $FREEM_LOG_THRESHOLD_SYSLOG .RS 4 Overrides the configured threshold at which log messages are sent to the \fIsyslog\fR facility on systems that support it, corresponding to the \fIlog_threshold_syslog\fR environment setting in \fI$PREFIX/etc/env.conf\fR. The default value is \fIinfo\fR. .RE .TP $FREEM_LOG_THRESHOLD_STDERR .RS 4 Overrides the configured threshold at which log messages are sent to \fIstderr\fR, corresponding to the \fIlog_threshold_stderr\fR environment setting in \fI$PREFIX/etc/env.conf\fR. The default value is \fIwarning\fR. .RE .SH LOG THRESHOLD VALUES This section details the valid values for each of the \fI$FREEM_LOG_THRESHOLD_*\fR environment variables, and each value indicates a minimum diagnostic level at which the indicated class of message will be delivered through the selected mechanism. All messages with an equal or higher diagnostic level than the class indicated will be delivered, i.e., if \fIwarning\fR is selected, messages with a diagnostic class of \fIwarning\fR, \fIerror\fR, and \fIfatal\fR will be delivered through the selected mechanism. Valid values for each of these environment variables are as follows: .TP debug .RS 4 Messages useful mostly for developers contributing to FreeM itself. Will produce a high volume of log messages, and is likely to impact system performance. Not recommended for production usage. .RE .TP info .RS 4 Includes messages of an informational nature. Will produce a moderately high volume of log messages. For heavily multi-user and multi-process systems, it is recommended to use \fIwarning\fR instead. .RE .TP warning .RS 4 Includes warning messages. These indicate conditions (including retries when attempting to acquire semaphores) that warrant further investigation by the system operator, but do not typically prevent applications from running. .RE .TP error .RS 4 Includes error messages. This class of messages indicates that a recoverable error has occurred in the FreeM engine. Warrants immediate attention by the system operator. .RE .TP fatal .RS 4 Includes messages indicating errors that are not recoverable. If this class of message occurs, the process that triggered the message has terminated abnormally. Requires immediate system operator intervention, and can indicate gross misconfiguration of the FreeM engine or the host operating system environment, or even a FreeM bug. .RE .SH FILES .PP $PREFIX/etc/freem/env.conf .RS 4 FreeM environment catalog .RE $PREFIX/etc/freem/<environment-name>/freem.conf .RS 4 FreeM per-environment configuration .RE .SH BUGS Check the issue tracker at https://bugs.coherent-logic.com for more detailed information on current bugs. .SH AUTHOR Authored, maintained and updated by Serena Willis (snw@coherent-logic.com) .SH COPYRIGHT Copyright (C) 2014, 2021, 2025 Coherent Logic Development LLC Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. .SH "SEE ALSO" .PP \fBfreem\fR(1), \fBenv.conf\fR(5), \fBfreem.conf\fR(5)