Return to fmadm.8 CVS log

Up to [Coherent Logic Development] / freem / doc

Fix texinfo bogosity and add subjects to man pages

    1: .\" To display this man page, either:
    2: .\"   1) Install this file along with the other subject.8 files in your
    3: .\"      system's man1 directory (usually this is /usr/man/man18) and
    4: .\"      enter the command:
    5: .\"        man fmadm
    6: .\"   or
    7: .\"   2) Specify the input (this file) and the output (your favorite pager)
    8: .\"      explicitly.  For example, if this file is in your current working
    9: .\"      directory, you can use the following to view the formatted man page
   10: .\"      using the "less" pager:
   11: .\"        man ./fmadm.8 | less
   12: .\"
   13: .\" To print this man page to a PostScript printer:
   14: .\"   man -t ./fmadm.8 | lpr
   15: .\"
   16: .\"   $Id: fmadm.8,v 1.6 2025/04/18 22:12:29 snw Exp $
   17: .\"    fmadm man page
   18: .\"
   19: .\"  
   20: .\"   Author: Serena Willis <snw@coherent-logic.com>
   21: .\"    Copyright (C) 2025 Coherent Logic Development LLC
   22: .\"
   23: .\"
   24: .\"   This file is part of FreeM.
   25: .\"
   26: .\"   FreeM is free software: you can redistribute it and/or modify
   27: .\"   it under the terms of the GNU Affero Public License as published by
   28: .\"   the Free Software Foundation, either version 3 of the License, or
   29: .\"   (at your option) any later version.
   30: .\"
   31: .\"   FreeM is distributed in the hope that it will be useful,
   32: .\"   but WITHOUT ANY WARRANTY; without even the implied warranty of
   33: .\"   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   34: .\"   GNU Affero Public License for more details.
   35: .\"
   36: .\"   You should have received a copy of the GNU Affero Public License
   37: .\"   along with FreeM.  If not, see <https://www.gnu.org/licenses/>.
   38: .\"
   39: .\"   $Log: fmadm.8,v $
   40: .\"   Revision 1.6  2025/04/18 22:12:29  snw
   41: .\"   Fix texinfo bogosity and add subjects to man pages
   42: .\"
   43: .\"   Revision 1.5  2025/04/18 01:23:05  snw
   44: .\"   More documentation updates
   45: .\"
   46: .\"   Revision 1.4  2025/04/17 17:57:35  snw
   47: .\"   Major updates to man pages
   48: .\"
   49: .\"   Revision 1.3  2025/04/17 15:08:24  snw
   50: .\"   Add documentation on FREEM_LOG_THRESHOLD environment variables to man pages
   51: .\"
   52: .\"   Revision 1.2  2025/04/04 12:49:19  snw
   53: .\"   Dollar signs cut off in ENVIRONMENT sections of both man pages
   54: .\"
   55: .\"   Revision 1.1  2025/04/03 15:56:41  snw
   56: .\"   Add fmadm man page to CVS
   57: .\"
   58: .\"
   59: .TH fmadm 8 "3 April 2025" FreeM "FreeM User Manual"
   60: .SH NAME
   61: fmadm - FreeM administrator tools
   62: .SH SYNOPSIS
   63: fmadm <action> <object> [-e=<environment] [-n=<namespace>] [OPTIONS]
   64: 
   65: fmadm configure [-e=<environment] [-n=<namespace>] [-u=<user>] [-g=<group>] [-E=true|false]
   66: 
   67: fmadm reconfigure [-e=<environment] [-n=<namespace>] [-u=<user>] [-g=<group>] [-E=true|false]
   68: 
   69: <action> can be one of:
   70:     list, examine, verify, remove, import, export, backup, restore,
   71:     edit, start, stop, restart, status
   72: 
   73: <object> can be one of:
   74:     lock, journal, namespace, global, routine, job,
   75:     environment
   76: 
   77: Running fmadm with no command-line arguments will start the interactive mode.
   78: .SH DESCRIPTION
   79: The
   80: .B fmadm
   81: program is a systems administration tool used by FreeM operators to manage their environments.
   82: 
   83: Please see the FreeM texinfo documentation for more details ("info freem").
   84: .SH FLAGS
   85: Please note that fmadm flags MUST consist of a hyphen, the letter representing the flag, an equal sign, and the value for the flag.
   86: 
   87: A valid flag looks like this:
   88: 
   89: \-e=DEFAULT
   90: 
   91: Spaces surrounding the equal sign, or a space in lieu of the equal sign, are
   92: invalid syntax.
   93: 
   94: .TP
   95: \-e
   96: .RS 4
   97: Sets the environment to be acted upon in this fmadm session.
   98: \fIDEFAULT\fR
   99: is assumed if this flag is not provided.
  100: .RE
  101: .TP
  102: \-n
  103: .RS 4
  104: Sets the namespace to be acted upon in this fmadm session.
  105: \fISYSTEM\fR
  106: is assumed if this flag is not provided.
  107: .RE
  108: .TP
  109: \-u
  110: .RS 4
  111: Sets the owning UNIX account of the environment.
  112: \fIfreem\fR
  113: is assumed if this flag is not provided. The UNIX account must already exist on your system.  Applies only to
  114: \fIfmadm configure\fR
  115: and
  116: \fIfmadm reconfigure\fR.
  117: .RE
  118: .TP
  119: \-g
  120: .RS 4
  121: Sets the owning UNIX group of the environment.
  122: \fIfreem\fR
  123: is assumed if this flag is not provided. The UNIX group must already exist on your system. Applies only to
  124: \fIfmadm configure\fR
  125: and
  126: \fIfmadm reconfigure\fR.
  127: .RE
  128: .TP
  129: \-E
  130: .RS 4
  131: Enables or disables an environment. Valid values are
  132: \fItrue\fR
  133: and
  134: \fIfalse\fR.
  135: \fItrue\fR
  136: is assumed if this flag is not provided. Applies only to
  137: \fIfmadm configure\fR
  138: and
  139: \fIfmadm reconfigure\fR.
  140: .RE
  141: .SH ACTIONS
  142: .TP
  143: configure
  144: .RS 4
  145: Configures an environment. No object will be used with this action. Instead, the
  146: \fI-e\fR,
  147: \fI-u\fR,
  148: \fI-g\fR, and
  149: \fI-E\fR flags will be referenced.
  150: .RE
  151: .TP
  152: reconfigure
  153: .RS 4
  154: Reconfigures an environment. No object will be used with this action. Instead, the
  155: \fI-e\fR,
  156: \fI-u\fR,
  157: \fI-g\fR, and
  158: \fI-E\fR flags will be referenced.
  159: .RE
  160: .TP
  161: list
  162: .RS 4
  163: Generates a list of <object>s. Applies to
  164: \fIlock\fR,
  165: \fIroutine\fR,
  166: \fIglobal\fR, and job.
  167: .RE
  168: .TP
  169: examine
  170: .RS 4
  171: Examines a specific instance of
  172: \fI<object>\fR. Applies to
  173: \fIroutine\fR,
  174: \fIglobal\fR,
  175: \fIjob\fR, and
  176: \fIjournal\fR.
  177: .RE
  178: .TP
  179: verify
  180: .RS 4
  181: Verifies the integrity of
  182: \fI<object>\fR. Applies to
  183: \fIglobal\fR.
  184: .RE
  185: .TP
  186: remove
  187: .RS 4
  188: Removes an instance of
  189: \fI<object>\fR. Applies to
  190: \fIjob\fR,
  191: \fIlock\fR,
  192: \fIroutine\fR, and
  193: \fIglobal\fR.
  194: .RE
  195: .TP
  196: import
  197: .RS 4
  198: Imports an instance of
  199: \fI<object>\fR. Applies to
  200: \fIroutine\fR (imports routine archives in RO/RSA format).
  201: .RE
  202: .TP
  203: export
  204: .RS 4
  205: Exports an instance of
  206: \fI<object>\fR. Applies to
  207: \fIroutine\fR (exports routine archives in RO/RSA format).
  208: .RE
  209: .TP
  210: backup
  211: .RS 4
  212: Backs up an instance of
  213: \fI<object>\fR. Applies to
  214: \fIroutine\fR.
  215: .RE
  216: .TP
  217: restore
  218: .RS 4
  219: Restores an instance of
  220: \fI<object>\fR. Applies to
  221: \fIjournal\fR (plays back after-image journals).
  222: .RE
  223: .TP
  224: edit
  225: .RS 4
  226: Edits an
  227: \fI<object>\fR. Applies to
  228: \fIroutine\fR (will open the routine in
  229: \fI$EDITOR\fR) and
  230: \fIglobal\fR (will open the interactive global editor).
  231: .RE
  232: .TP
  233: start
  234: .RS 4
  235: Starts one environment, multiple environments, or all environments. Applies to
  236: \fIenvironment\fR.
  237: .RE
  238: .TP
  239: stop
  240: .RS 4
  241: Stops one environment, multiple environments, or all environments. Applies to
  242: \fIenvironment\fR.
  243: .RE
  244: .TP
  245: restart
  246: .RS 4
  247: Restarts one environment, multiple environments, or all environments. Applies to
  248: \fIenvironment\fR.
  249: .RE
  250: .TP
  251: status
  252: .RS 4
  253: Gets the status of one environment, multiple environments, or all environments. Applies to
  254: \fIenvironment\fR.
  255: .RE
  256: .SH "FURTHER INFORMATION"
  257: Please note that the primary documentation for FreeM is the 'info' manual, accessed with the following command:
  258: 
  259: \fIinfo freem\fR
  260: 
  261: These manual pages are minimal, and maintained on a strictly best-effort basis.
  262: .SH "RETURN VALUES"
  263: Returns 0 for non-error condition.
  264: .SH FILES
  265: .TP
  266: env.conf
  267: .RS 4
  268: The FreeM environment catalog. Normally located in $PREFIX/etc/freem/env.conf
  269: .RE
  270: .TP
  271: freem.conf
  272: .RS 4
  273: The FreeM configuration file. Normally located in $PREFIX/etc/freem/<environment-name>/freem.conf.
  274: .RE
  275: .SH ENVIRONMENT
  276: .TP
  277: $EDITOR
  278: .RS 4
  279: Determines the text editor used by
  280: \fIedit routine\fR.
  281: .RE
  282: .TP
  283: $FREEM_LOG_THRESHOLD_FILE
  284: .RS 4
  285: Overrides the configured threshold at which log messages are written to files in
  286: \fI/var/log/freem\fR, corresponding to the
  287: \fIlog_threshold_file\fR environment setting in
  288: \fI$PREFIX/etc/env.conf\fR. The default value is
  289: \fIinfo\fR.
  290: .RE
  291: .TP
  292: $FREEM_LOG_THRESHOLD_SYSLOG
  293: .RS 4
  294: Overrides the configured threshold at which log messages are sent to the
  295: \fIsyslog\fR facility on systems that support it, corresponding to the
  296: \fIlog_threshold_syslog\fR environment setting in
  297: \fI$PREFIX/etc/env.conf\fR. The default value is
  298: \fIinfo\fR.
  299: .RE
  300: .TP
  301: $FREEM_LOG_THRESHOLD_STDERR
  302: .RS 4
  303: Overrides the configured threshold at which log messages are sent to
  304: \fIstderr\fR, corresponding to the
  305: \fIlog_threshold_stderr\fR environment setting in
  306: \fI$PREFIX/etc/env.conf\fR. The default value is
  307: \fIwarning\fR.
  308: .RE
  309: .SH LOG THRESHOLD VALUES
  310: This section details the valid values for each of the
  311: \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
  312: \fIwarning\fR is selected, messages with a diagnostic class of
  313: \fIwarning\fR,
  314: \fIerror\fR, and
  315: \fIfatal\fR will be delivered through the selected mechanism.
  316: 
  317: Valid values for each of these environment variables are as follows:
  318: .TP
  319: debug
  320: .RS 4
  321: 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.
  322: .RE
  323: .TP
  324: info
  325: .RS 4
  326: 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
  327: \fIwarning\fR instead.
  328: .RE
  329: .TP
  330: warning
  331: .RS 4
  332: 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.
  333: .RE
  334: .TP
  335: error
  336: .RS 4
  337: 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.
  338: .RE
  339: .TP
  340: fatal
  341: .RS 4
  342: 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.
  343: .RE
  344: .SH FILES
  345: .PP
  346: $PREFIX/etc/freem/env.conf
  347: .RS 4
  348: FreeM environment catalog
  349: .RE
  350: 
  351: $PREFIX/etc/freem/<environment-name>/freem.conf
  352: .RS 4
  353: FreeM per-environment configuration
  354: .RE
  355: .SH BUGS
  356: Check the issue tracker at https://bugs.coherent-logic.com for more detailed information on current bugs.
  357: .SH AUTHOR
  358: Authored, maintained and updated by Serena Willis (snw@coherent-logic.com)
  359: .SH COPYRIGHT
  360: Copyright (C) 2014, 2021, 2025 Coherent Logic Development LLC
  361: 
  362: 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.
  363: 
  364: .SH "SEE ALSO"
  365: .PP
  366: \fBfreem\fR(1),
  367: \fBenv.conf\fR(5),
  368: \fBfreem.conf\fR(5)