Using FCPUTIL for server maintenance
About FCPUTIL
FCPUTIL is a FirstClass Protocol utility designed to check the status of the server and perform some commands related to maintaining the server. It requires an account with "Monitor server" and "Maintain server" privileges, and it can be used across a network.
There are some major advantages of using FCPUTIL over other options such as NET Pause or fcsctl pause:
• FCPUTIL can return the status of an action. Therefore a script can be constructed to deal with the returned status.
• It supports considerably more functions than the NET command's STOP, PAUSE, and CONTINUE.
• It is both network-based and platform-independent, so it can be run from a different machine than the one hosting the server, and even a different platform.
Setting up FCPUTIL
FCPUTIL is installed automatically with the FirstClass Server, so all you need to do is set it up, which can be done in three steps:
STEP 1: Create a user account
STEP 2: Create a settings file
STEP 3: Customize the account
STEP 1: Create a user account
 NoteYou do not need to set up a new account, but we recommend that you do, since the common alternative would be to use the admin account. If you choose not to set up a new account, make sure the account you use has the "Monitor server" and "Maintain server" privileges.
1 Create a new user and give the new account a strong password.
2 Give it two additional privileges: "Monitor server" and "Maintain server".
3 Make sure this account is a member of a group which has the ability to save passwords.
Note
This account does not need to be a subadmin account.
STEP 2: Create a settings file
1 Go to the folder where your FirstClass executable files exist.
2 Make a copy of a settings file such as Inetsvcs.fc, and rename the copy to fcputil.fc.
STEP 3: Customize the account
1 Launch the FirstClass client.
2 Click Browse.
3 Find the folder where FirstClass is installed, and open the fcputil.fc settings file.
Note
The fcputil.fc file must be stored in the same location as the FirstClass executable files.
4 Enter the user id and password for the account and click Save.
5 Log in with the FirstClass client to make sure that the client can connect to a server using this settings file.
Common errors
The two most common errors when setting up FCPUTIL are:
1003 |
Username or password is incorrect. Also, make sure the account has the appropriate permissions (Monitor server and Maintain server). |
4105 |
fcputil.fc is not in the same location as FCPUTIL, or the account is not set up properly. Review the steps above. |
Syntax
Run FCPUTIL with the command to process and any additional arguments specific to that command.
Usage: fcputil <cmd> [parameter] [SERVER || FCS || IS || FCINTSRV || VS || VSERVICE]
or: fcputil [-s|-S] getstats [id [id ...] ]
or: fcputil -h - gives the basic syntax help plus common commands
or: fcputil -H - gives syntax with a full list of command keywords
Switches
Switch |
Meaning |
-h |
displays command help for the most commonly used operations |
-H |
displays complete list of all commands available |
-v |
displays FCPUTIL version |
-s |
see GETSTATS for information |
-S |
see GETSTATS for information |
Common core commands
Command |
Meaning |
Parameters |
ABOUT |
|
|
displays the server version (in the server console/log file) |
AUDIT |
|
|
starts an audit on the core server |
BROADCAST |
"message" |
|
send a broadcast to all users logged in |
DISABLE |
|
|
disables all logins (except for admin/subadmin/maintenance users) |
ENABLE |
|
|
enables logins by all users and services |
FAST |
|
|
performs a fast (normal) shutdown |
LOGOFF |
userid |
|
forces logoff of the specified user |
POLITE |
|
|
performs a polite shutdown |
QUIT |
|
|
tells the server to terminate/exit (for the server, this is the same as FAST) |
STOPAUDIT |
|
|
force the audit to stop (after the audit of the current folder completes) |
TC |
|
|
an alias for the AUDIT command above |
TRASH |
|
|
an alias for the AUDIT command above |
WAIT |
n |
|
pauses fcputil for the specified number of seconds, where n represents number of seconds. Note This command is local-only. This means it does not communicate with the server end and therefore does not require a settings file to use it. |
Backup, mirroring, and snapshot hold commands
Command |
Meaning |
Parameters |
CONTINUE or CONT |
|
|
releases the mirror from the paused state triggered by PAUSE; returns 0 if successful, FirstClass error code if unsuccessful |
HOLD |
n |
|
puts the server into "snapshot hold", a paused state for the specified number of seconds, where n represents the number of seconds |
MCHECK |
|
|
returns the current state of the mirror as an error level-compatible return code: 0: All mirrors are paused. 1: No volumes are mirrored. 2:
All mirrors are synchronized and active. 3: At least one mirrored volume is still synchronizing. 4: Mirror status varies depending on the mirrored volume. 5: At least one mirror has failed. |
MDUMP |
|
|
returns the current state of the mirror (see MCHECK) and dumps the current status as text in the console/log file |
MIRRORLOG |
|
|
toggles the display of mirroring-related debug messages to the console/log file |
PAUSE |
|
|
pauses the mirror until CONTINUE command is issued; returns 0 if successful, FirstClass error code if unsuccessful |
QSHOW |
|
|
displays a detailed list of the mirroring queue  CautionOutput may be extremely large. |
QSUMMARY |
|
|
displays a summary of the mirroring queue |
RESYNC |
|
|
forces a full mirror resync of all mirrors; returns 0 if successful, FirstClass error code if unsuccessful |
Performance and statistics commands
Command |
Meaning |
Parameters |
GETSTATS |
|
|
|
MEM |
|
|
displays a summary of memory use in the server console/log file |
PRESET |
|
|
resets the performance statistics reported in the PSTATS command |
PSTATS |
|
|
dumps a summary of performance-related statistics to the console/log file |
Other core commands
Command |
Meaning |
Parameters |
GATEWAY or NOW or REPLICATE |
gateway-name |
|
forces a gateway to connect |
HIGH |
|
|
sets the internal server priority to high |
LOW |
|
|
sets the internal server priority to low |
MEDIUM or MED |
|
|
sets the internal server priority to medium |
Other current status commands
Command |
Meaning |
Parameters |
GATEWAYS |
|
|
dumps a list of gateways to the console/log file |
GROUPS |
|
|
dumps a list of groups to the console/log file |
LISTFILES |
|
|
dumps a list of all open files to the console/log file Caution Dangerous, as large sites have tens of thousands of these. |
LISTOBJS |
|
|
dumps a list of all open objects to the console/log file Caution Dangerous, as large sites have many of these. |
NOTIFY |
|
|
dumps the notify table to the console/log file |
SESSION or SESSIONS |
|
|
displays the status of sessions to the console/log file |
STATS |
|
|
displays some server summary statistics |
STATUS |
|
|
another (different) status summary of sessions |
TASKS |
|
|
dumps a list of server tasks to the console/log file |
Indexing commands
Command |
Meaning |
Parameters |
INDEXFLUSHDATA |
|
|
flushes from memory the dictionary and document data |
INDEXFLUSHFWD |
|
|
flushes from memory forward index data |
INDEXFLUSHUNSEARCHED |
|
|
flushes from memory objects that haven't been used to satisfy searches |
INDEXPAUSEBACKUP |
|
pauses backup of the index |
INDEXPAUSEINDEXING |
|
|
pauses indexing |
INDEXRESUMEBACKUP |
|
resumes index backup when it has been paused |
INDEXSKIPFWDSAVE |
|
|
skips saving forward index data to disk, enabling you to write a script so that when power is lost and the server is running on UPS, it can be shut down faster |
INDEXSTATUS |
|
returns one of the following index states: 0 - indexing running normally 1 - clean up queued 2 - flushing 3 - critical data flushed and closed |
You can use INDEXPAUSEBACKUP, INDEXRESUMEBACKUP, and INDEXSTATUS to use scripting to back up the index, as in this example:
fcputil IndexPauseBackup
loop:
rc = fcputil IndexStatus
if rc == 3
run backup
fcputil IndexResumeBackup
exit
goto loop
Common logging commands
Command |
Meaning |
Parameters |
CONSOLE |
|
|
toggles the console to file option, which in modern servers means turn fcs.log file logging on or off |
CONSOLELOG |
|
|
forces the console log to be enabled (not a toggle) |
LOGINLOG |
|
|
toggle the reporting of all logins and logoffs to the console/log file |
MAILLOG or MAIL |
|
|
toggles message (MTA) delivery logging |
NOCONSOLELOG |
|
|
forces the console log to be disabled (not a toggle) |
Other logging and debugging commands
Command |
Meaning |
Parameters |
BATCHADMIN or REMADMIN |
|
|
enables server logging for FC script (batch admin) operations |
DB |
|
|
toggles database extension logging on/off |
DBGALL or DEBUG |
|
|
enables full server debug logging |
DBGCORE |
|
|
enables server debug logging for core server operations |
DBGDIR |
|
|
enables server debug logging for user directory operations |
DBGFILE |
|
|
enables server debug logging for file I/O operations (mostly core buffering messages) |
DBGIS |
|
|
enables server debug logging for services (such as IS) |
DBGNONE |
|
|
disables all server debug logging |
DBGSESS |
|
|
enables server debug logging for session-related operations |
DBGTC |
|
|
enables server debug logging for audit operations |
GWCDATA |
|
|
toggles reporting of gateway client protocol debugging - data dumps |
GWCDEBUG |
|
|
enables full (verbose) reporting of gateway client protocol |
GWCNONE |
|
|
disables reporting of gateway client protocol debug messages |
GWCOPEN |
|
|
enables gateway client protocol debugging - opens and closes |
GWCWARN |
|
|
enables gateway client protocol debugging - warning messages |
GWMAIL |
|
|
enables gateway client protocol debugging - mail-related operations |
PACKET |
|
|
enables full packet debugging logging, including packet data contents |
PKTCONN |
|
|
enables connection-related packet debugging messages to the console/log file |
PKTERR |
|
|
enables packet error debugging messages to the console/log file |
PKTMOST |
|
|
enables all packet debugging messages except send/received packet data to the console/log file |
PKTNONE |
|
|
disables all packet debugging messages |
PKTSTAT |
|
|
dumps several packet-related statistics to the console/log file |
PKTRX |
|
|
enables the dumping of received packets debugging messages to the console/log file |
PKTTX |
|
|
enables the dumping of sent packets debugging messages to the console/log file |
Examples
This script incorporates multiple FCPUTIL commands. It warns users that a shutdown is imminent, and then performs a fast shutdown.
FCPUTIL BROADCAST "Server shutdown in 5 minutes."
FCPUTIL WAIT 240
FCPUTIL BROADCAST "Server shutdown in 1 minute. Please log off."
FCPUTIL WAIT 60
FCPUTIL BROADCAST "Server shutting down now."
FCPUTIL WAIT 5
FCPUTIL FAST
This is the output to the console/log file that resulted from two MDUMP commands. One was issued while the mirror was still synchronizing, and the other was issued after synchronization was complete:
[2010/03/01 01:32:04] Volume 8001 ("G:") mirror state is FULL SYNC (90%).
[2010/03/01 01:32:04] Volume 853C ("E:") mirror is ACTIVE.
[2010/03/01 01:32:54] Mirror: Beginning incremental sync of 13 item(s) ...
[2010/03/01 01:33:01] Mirror: Incremental sync of 13 item(s) complete.
[2010/03/01 01:33:01] Mirror: Volume 8001 sync complete. Mirror active.
[2010/03/01 01:34:57] Volume 8001 ("G:") mirror is ACTIVE.
[2010/03/01 01:34:57] Volume 853C ("E:") mirror is ACTIVE.
This script pauses the server and takes a snapshot copy of the network store:
fcputil.exe hcheck
IF ERRORLEVEL 0 echo %ERRORLEVEL% & goto initbackup
goto end
:initbackup
START fcputil hold 60
:waitforhold
IF EXIST snapshot goto backup
fcputil wait 20
rem if a fall back test needed - fcputil.exe hcheck
rem IF ERRORLEVEL 0 echo %ERRORLEVEL% & goto end
goto waitforhold
:backup
rem Backup ALL FirstClass mirror volumes
echo FirstClass mirror paused. Backing up FCNS mirror files, please wait ...
echo %TIME%
rem Take NetApp snap shot of the paused mirror.
echo Taking a snap shot ...
rem rsh localhost -l userid:password -n snap create vol3 weekly.temp
rem Wait for NetApp volume commands to complete.
echo FCNS backup completed.
del snapshot
rem if this fails, it means the 60 seconds is up and the server resumed and it deleted the file
:end
rem Delete the file created at the top of this script.
del fcIndexbackup.run
rem If this script terminates abnormally, the file fcshold.run rem MUST be removed from the FCServer folder manually. Until this is done this script will abort on startup.
echo %TIME%
echo Script Processing complete.
EXIT /b
This script pauses indexing and takes a copy:
fcputil.exe IndexStatus
IF ERRORLEVEL 4 echo %ERRORLEVEL% & goto end
IF ERRORLEVEL 3 echo %ERRORLEVEL% & goto backup
IF ERRORLEVEL 2 echo %ERRORLEVEL% & goto waitforhold
IF ERRORLEVEL 1 echo %ERRORLEVEL% & goto waitforhold
IF ERRORLEVEL 0 echo %ERRORLEVEL% & goto initbackup
goto end
:initbackup
fcputil.exe IndexPauseBackup 40
IF ERRORLEVEL 0 echo %ERRORLEVEL% & goto waitforhold
goto end
:waitforhold
fcputil.exe wait 10
fcputil.exe IndexStatus
IF ERRORLEVEL 4 echo %ERRORLEVEL% & goto resume
IF ERRORLEVEL 3 echo %ERRORLEVEL% & goto backup
IF ERRORLEVEL 2 echo %ERRORLEVEL% & goto waitforhold
IF ERRORLEVEL 1 echo %ERRORLEVEL% & goto waitforhold
IF ERRORLEVEL 0 echo %ERRORLEVEL% & goto end
goto end
:backup
echo FirstClass Index paused. Backing up files, please wait ...
echo %TIME%
echo Taking a copy of index ...
fcputil wait 20
echo Index backup completed.
rem if this fails, it means the 60 seconds is up and the server resumed and it deleted the file
:resume
fcputil.exe IndexResumeBackup
:end
echo %TIME%
echo Script Processing complete.
EXIT /b
GETSTATS command
This command provides the ability to fetch real-time statistics from the server remotely by requesting a static number from the server that corresponds to the desired function.
Syntax
The syntax for the GETSTATS command is:
FCPUTIL [ -s | -S ] GETSTATS [ <stat-IDs> ... ]
Statistics IDs
Here is a full list of the statistics IDs and their values. Commonly used statistics are identified with *.
Name |
ID |
Description |
Subsystem stats |
|
|
General stats |
StatCounter |
0 |
starts at 1, increments every time stats are returned |
*Sanity |
1 |
always returns a value of 1 |
Version |
2 |
always returns the current server version (e.g. 8.000) |
Build |
3 |
always returns the current server build number (e.g. 200.0) |
Task stats (incremental) |
LastReset |
1000 |
milliseconds since previous stats reset |
Loops |
1101 |
iterations through task list |
Tasks |
1102 |
total number of tasks scheduled |
IO |
1103 |
I/O operations requested |
AsyncIO |
1104 |
I/O operations gone async (IOList) |
Idle |
1105 |
times Idler scheduled |
WakeIdle |
1106 |
times sleeping tasks wake due to idle |
Suspend |
1107 |
times tasks removed from ready list |
HotTasks |
1108 |
times tasks scheduled from hot list |
*Longest |
1109 |
longest latency on task loop for interval |
Task stats (cumulative) |
TLoops |
1201 |
iterations through task list |
TTasks |
1202 |
total number of tasks scheduled |
TIO |
1203 |
I/O operations requested |
TAsyncIO |
1204 |
I/O operations gone async (IOList) |
TIdle |
1205 |
times Idler scheduled |
TWakeIdle |
1206 |
times sleeping tasks wake due to idle |
TSuspend |
1207 |
times tasks removed from ready list |
THotTasks |
1208 |
times tasks scheduled from hot IO list |
TLongest |
1209 |
longest latency on task loop over period |
TAverage |
1210 |
average latency on task loop over period |
File stats (incremental) |
*Opens |
1301 |
total number of file open *requests* |
Reads |
1302 |
read operations requested |
ReadHits |
1303 |
read operations satisfied from SAFile cache |
ReadSysHits |
1304 |
read operations satisfied from file system cache |
ReadBytes |
1305 |
bytes transferred during read operations |
Writes |
1306 |
write operations requested |
WriteHits |
1307 |
write operations satisfied from SAFile cache |
WriteSysHits |
1308 |
write operations satisfied from file system cache |
WriteBytes |
1309 |
bytes transferred during write operations |
File stats (cumulative) |
TOpens |
1401 |
total number of file open *requests* |
TReads |
1402 |
read operations requested |
TReadHits |
1403 |
read operations satisfied from SAFile cache |
TReadSysHits |
1404 |
read operations satisfied from file system cache |
TReadBytes |
1405 |
bytes transferred during read operations |
TWrites |
1406 |
write operations requested |
TWriteHits |
1407 |
write operations satisfied from SAFile cache |
TWriteSysHits |
1408 |
write operations satisfied from file system cache |
TWriteBytes |
1409 |
bytes transferred during write operations |
Other file stats |
*Open |
1400 |
total number of files currently open |
FirstClass server stats |
Timed performance statistics |
MS |
2001 |
milliseconds for this period |
TPL |
2002 |
ticks per loop |
LPS |
2003 |
loops per second |
TPS |
2004 |
task switches per second |
*Usage |
2005 |
the Task Load indicator (percentage) |
The other two Summary load bars |
*DiskAvg |
2011 |
average disk response time (including server overhead) |
*DiskLoad |
2012 |
same as above but converted to arbitrary load % bar |
*ServerAvg |
2021 |
average server response time |
*ServerLoad |
2022 |
same as above but converted to arbitrary load % bar |
Disk operations (system requests) |
*DiskOps |
2030 |
total # disk ops (incrementing) |
DiskOpsMTA |
2031 |
total # disk ops by the superhot task, typically the MTA (incrementing) |
Snapshot server statistics |
*Connected |
2102 |
current number of network connections (including remote) |
Priority |
2103 |
0=prDedicated (High), 1=prSharedApp (Med), 2=prBackground (Low) |
SessionLED |
2104 |
0=normal, 1=warning, 2=usage at or beyond 100% |
*Logins |
2105 |
total number of logins |
*Remote |
2106 |
current number of remote session licenses in use (requires 8.0 Build 242 server or later) |
Other misc server stats |
SessionLimit |
2110 |
per-session memory limit |
*AuditProgress |
2111 |
complete, or 100 if not running
|
Server Monitor times |
LastFileReset |
2201 |
last "Reset" for "Files" tab or server start time |
LastTaskReset |
2202 |
last "Reset" for "Tasks" tab or server start time |
ServerBoot |
2203 |
server startup time |
Message queue stats |
*Deliveries |
2301 |
messages delivered |
*Active |
2302 |
messages awaiting immediate delivery |
Urgent |
2303 |
urgent messages queued |
UrgentQ |
2304 |
percentage of queue filled |
Normal |
2305 |
normal messages queued |
NormalQ |
2306 |
percentage of queue filled |
Bulk |
2307 |
bulk messages queued |
BulkQ |
2308 |
percentage of queue filled |
Junk |
2309 |
junk messages queued |
JunkQ |
2310 |
percentage of queue filled |
Held |
2311 |
held messages queued |
HeldQ |
2312 |
percentage of queue filled |
Delayed |
2313 |
delayed messages queued |
DelayedQ |
2314 |
percentage of queue filled |
System stats |
|
|
Memory stats |
MemAppTotal |
9001 |
total system memory available to the server, after limiting factors (e.g. address space) |
*MemAppAvail |
9002 |
available system memory for server use, after limiting factors (e.g. address space) |
MemVirtTotal |
9003 |
total virtual memory on the server machine |
MemVirtAvail |
9004 |
virtual memory available to the server on the server machine |
MemAddrTotal |
9005 |
total address space for the server process |
MemAddrAvail |
9006 |
address space currently available for the server use |
MemPhysTotal |
9007 |
total physical memory on the server machine |
MemPhysAvail |
9008 |
available physical memory on the server machine |
Examples
This command returns the three server load percentages normally displayed on the Summary tab of the Server Monitor.
FCPUTIL GETSTATS 2005 2012 2022
The output would be something like:
C:\>FCPUTIL GETSTATS 2005 2012 2022
FCPUtil Version 8.0.5 [Nov 22 2004]
Copyright (c) 2004 by OpenText Corporation
Stat ID Current Statistic Value
======= =======================
2005 0.000
2012 0.220
2022 0.000
3 statistics returned.
Note
If no stat IDs are specified, FCPUTIL uses a default list of "2 3 2005 2012 2022 1400 2111 2301 2302 9002".
For the purposes of more automated procedures, there are two options (-s and -S) to reduce the complexity and verbosity of the output.
-s returns an "ID=value" formatted list:
C:\>FCPUTIL -s GETSTATS 2005 2012 2022
2005=0.000 2012=0.235 2022=0.000
-S just returns a list of values:
C:\>FCPUTIL -S GETSTATS 2005 2012 2022
0.000 0.358 0.000
A common example for tracking server performance might be the default stats list in the terse format:
C:\>FCPUTIL -S GETSTATS
8.000 203.000 0.000 0.231 0.000 44.000 100.000 0.000 0.000 1072410624.000
| 
Note