FileMaker Server UPS Shutdown Using the

FileMaker Server UPS Shutdown Using the Command Line
Create a OS X shell script to safely shut down FileMaker Server in the event of a power outage.
By Todd Duell
There
comes a point as a FileMaker
administrator when you have to address the
issue of how to automate the safe shut down
of your FileMaker Server in the event of a
power failure. Just having a UPS power
backup isn’t enough. The problem is if you
don’t have a sophisticated power backup
system, such as a generator, you may only have a few
minutes to power down your servers. That’s obviously a
problem if the power goes out in the middle of the night,
which seems to be the most common time when it happens.
This article will show you how to use the fmsadmin
command line on OS X to create a shell script that can be
used in conjunction with your UPS backup software to safely
power down your server so the databases won’t become
corrupted as a result of the power inadvertently being shut
off. This article will also provide additional reference material
regarding the fmsadmin commands if you need to control the
server from the command line.
There are many flavors of UPS backup hardware and
software available. The most common vendor is APC and
even they have multiple versions of their backup software. You’ll
need to reference their documentation to enable their software
to power down your server either through a direct USB or
network connection. If you have a USB connection with the UPS
backup power supply and have installed their software on the
server you’ll most likely find the controls to power down the
server in the System Preferences>Energy Saver screen. If not,
you may be able to access the settings through the UPS
software. The most important setting will be when to have the
UPS software shut down the server, such as how much time or
charge is left on the battery. That way if the power comes back
on the server won’t be shut down just because of a quick power
outage or brownout. You’ll also need to configure the UPS
software to run a shell script to power off FileMaker Server since
it can’t communicate directly with FileMaker Server to shut down
the service. You will point the UPS setting to run the shell script
that we’ll create next.
For simplicity sake I’m going to create a shell script that
assumes that there is a power outage and you need to close all
the databases and disconnect all the users before the power
shuts off. You don’t need anything fancy. It’s an emergency and
your primary goal is to prevent the databases from being
corrupted as a result of a power loss. You can live with the
Todd Duell is the Vice President & CIO of Formulations Pro, Inc and has been creating powerful commercial and custom solutions using FileMaker Pro since 1989. He holds an
MBA in Technology Management, is a Certified FileMaker Pro Developer, and has been a member of the FileMaker Business Alliance since 1998. Author of FileMaker API for
PHP, A Practical Guide for Creating Database Driven Web Sites with FileMaker Pro 12 and FileMaker Server 12. Todd may be reached at [email protected]
© 2013 Formulations Pro, Inc. All rights reserved. www.formulationspro.com
potential loss of a few records that people were updating on
their FileMaker Pro client. The users can re-enter the data
when the power comes back on. The first step is to open the
Terminal application from the Utilities folder. You need to
create the shell script in a pure text file rather than TextEdit,
which adds hidden return carriages and line feeds that cause
the shell script to fail. With Terminal open, open the pico text
editor by typing “pico”
forces the databases to close using the option –f and answers
“yes” with option s to all subsequent dialog boxes so you don’t
have to answer them manually. Then it passes the FileMkaer
Server Admin Console user name and password with –u and –
p. For this demo the user name is fms and the password is
XXXX. You need to enter your server’s real information here.
Figure 2 fmsadmin — Create the close script.
Figure 1 Pico — Open the pico text editor.
Next, type the following 2 lines:
#!/bin/bash
fmsadmin CLOSE -fy -ufms –pXXXX
The first line forces the shell script to run using bash
as the command line application. The second line uses the
fmsadmin command CLOSE to close all open databases. It
To create the file choose WriteOut by typing control-O.
Give the file a name, such as fms_close.sh. Using the .sh
extension is necessary later so the file can be made an
executable shell script. The file will be written out to the home
folder of the account you are logged in as (in a finder window
that the one with the little house icon listed in Places). You can
drag the file to your desktop so it’s easy to find for the next step.
Then exit out of the pico text editor by typing control-X.
Page 2
Figure 3 fms_close.sh — Save the file.
Figure 4 Destop — Move the file to your desktop so it’s easy to find.
With the shell file created we need to enable it to be
executable. Type cd desktop in your text editor to navigate to
the desktop. If you want to check to make sure the file is
present on the desktop you can use the command ls –al. To
make the file executable type chmod +x fms_close.sh. If you
use the command ls –al again you’ll be able to see the file
has been changed to executable –rwxr-xr-x with x added to
all the privileges. You might be asking why you have to do
this with Terminal instead of right-clicking the file and
choosing Get Info to change the permission? It’s because
you can only make a file read and write from Get Info.
Whereas, you have to make it executable from the Terminal.
Dam you UNIX and Apple!!!
That’s it. You just created the shell script to close all
the database files and made it executable. Now you can set
up your UPS software to run the script at the desired time.
Figure 5 Executable — Make the shell script executable.
Page 3
FileMaker Server Command Line Reference
Figure 6 Executable — Verify that the fms_close.sh file is
executable.
The following information can all be acquired from the Terminal
by typing “fmsadmin help commands” and “fmsadmin help
options”. Commands will get you a list of all 19 commands from
autorestart to verify. Options will get you a list of all the general
options and specific commands that you can use with each
command. The most common being –f for force, -y for
automatically respond with “yes” to message from the terminal
and –u and –p for the user name and password for FileMaker
Server Admin Console. Outside of that you’ll probably need to
refer to this reference information to do anything else through
the Terminal as the Admin Console can do all of this a lot
easier. Outside of a power failure shutdown script if you need to
use the command line you should really ask yourself “why”. I’ve
also experienced some bugs for commands that do not work on
FileMaker Server 12 and have reported them to FileMaker. Who
knows if and when they will ever be fixed. Therefore, if
something doesn’t appear to be working and you followed the
documentation, it could very well be a bug.
Page 4
fmsadmin commands
fmsadmin help options
Description: fmsadmin is the command line tool to administer
the Database Server component of FileMaker Server
installed on the local machine.
Many fmsadmin commands take options and parameters.
You can script many tasks with fmsadmin by using a
scripting language that allows execution of shell or terminal
commands.
Short Options: Specify single-character options after a single
hyphen (-). You can specify multiple options together. If an
option requires a parameter, that option is usually the last option
that you specify. For example:
fmsadmin close -ym 'Closing for maintenance' Database.fp7
fmsadmin HELP COMMANDS
Lists available commands
fmsadmin HELP [COMMAND]
Displays help on the specified COMMAND
fmsadmin HELP OPTIONS
Lists available options
Also see "Command line reference" in FileMaker Server
Help: http://localhost:16000/admin-help/en
A space is optional between the option character and the
parameter. For example:
fmsadmin close -mGoodbye
Long Options: Specify long options after two hyphens (--). Long
options can be used in scripts to increase readability. A space is
required between the option and any parameters. For example:
fmsadmin close --yes --message "Closing for maintenance"
Database.fp7
Parameters: Enclose any parameters that contain spaces in
single or double quotation marks (' or "). Symbols that may be
interpreted by the shell must be escaped, that is, preceded by a
backslash character (\). Refer to the documentation for your
shell or command interpreter.
General Options:
-h, --help
Print this page.
Page 5
-p pass, --password pass Password to use to authenticate
with the server.
-u user, --username user Username to use to authenticate
with the server.
-v, --version
-o, --offline
Perform an offline backup.
-s, --stats
Return FILE or CLIENT stats.
-t sec, --gracetime sec
forced to disconnect.
Specify time in seconds before client is
Print version information.
-x, --verify
Verify integrity of each backup file.
-w seconds, --wait seconds Specify time in seconds for
command to time out.
-y, --yes
prompts.
Automatically answer yes to all command
Options that apply to specific commands:
-d PATH, --dest PATH
path.
-f, --force
Server
Specify a backup destination
Force database to close or Database
to stop, immediately disconnecting
clients.
-k count, --keep count
-m msg, --message msg
to clients.
-n, --clone
verify.
Specify count of backups to keep.
Specify a text message to send
Clone each backup file after optional
Page 6
fmsadmin help commands
RESUME
Make paused databases available
fmsadmin commands are:
RUN
AUTORESTART
Server
BACKUP
CLOSE
Get or set auto-restart for the Admin
SEND
Back up databases
Close databases
CERTIFICATE
DISABLE
LIST
Get status of clients or databases
Manage SSL certificates
Disable schedules
DISCONNECT
HELP
Send a message
START
Start the SERVER, ADMINSERVER, FMSE,
WPE, or XDBC process
STATUS
ENABLE
Run a schedule
Disconnect a client
STOP
Stop the SERVER, ADMINSERVER, FMSE, WPE,
or XDBC process
VERIFY
Check the consistency of databases
Enable schedules
Get help pages
List clients, databases, plug-ins, or schedules
OPEN
Open databases
PAUSE
Temporarily stop database access
REMOVE
Move databases out of hosted folder or
remove empty folder
RESTART
Restart the SERVER, ADMINSERVER,
FMSE, WPE, or XDBC process
Page 7
fmsadmin autorestart
This command works only if the FileMaker Server service
(Windows) or fmserver_helperd daemon (Mac OS) is running.
Usage: fmsadmin AUTORESTART ADMINSERVER [FLAG]
Options:
No command specific options.
Description:
Enables or disables auto-restart for the Admin Server if a
valid FLAG is specified. If you don't specify a FLAG, the
current auto-restart setting is displayed.
Valid FLAGs:
ON
OFF
Turn on auto-restart.
Turn off auto-restart.
The FileMaker Server service (Windows) or the
fmserver_helperd daemon (Mac OS) starts and monitors the
Admin Server process. If you turn ON auto-restart, FileMaker
Server will automatically restart the Admin Server process
whenever it has stopped or is not responding for more than
sixty seconds.
If you stop the Admin Server process by using the 'fmsadmin
STOP ADMINSERVER' command, FileMaker Server stops
monitoring the process, but the auto-restart setting is not
changed.
The default setting for auto-restart is ON. The auto-restart
OFF setting is not persistent; whenever the FileMaker Server
service or fmserver_helperd daemon starts, auto-restart is
automatically turned ON.
Page 8
fmsadmin help backup
filemac:/volumeName/folderName/
Usage: fmsadmin BACKUP [FILE...] [PATH...] [options]
-k count, --keep count
Specify count of backups to keep (default is 1). If count is nonzero, a timestamped backup folder will be created in the
destination, andup to that count of timestamped backup folders
will be kept, if disk space permits. If count is zero, no
timestamped folder is created, andthe backup file structure and
optional clones are written in thedestination, overwriting any files
of the same name.
Description:
Backs up the specified databases (FILE) or all the hosted
databases in the specified folders (PATH).
By default, the BACKUP command performs a live backup of
a hosted database, without interfering with client usage.
Alternatively, first PAUSE the databases, then issue the
BACKUP command, followed by a RESUME command to
perform an offline backup. If you don't specify a destination
path, the databases are backed up to the default backup
folder. If you don't specify a database or folder to back up, all
hosted databases are backed up.
-n, --clone
Clone each backup file after optional verify.
-x, --verify
Verify integrity of each backup file.
You can use options to verify and clone your backup file after
the backup has completed. A clone of a database contains
all the field definitions, tables, layouts, scripts, etc., but none
of the record data.
Options:
-d PATH, --dest PATH
Overrides the default backup folder destination by backing
up the databases to the specified path. If the path doesn't
exist, FileMaker Server attempts to create it. The path to a
folder must end with the slash (/) character, for example:
filewin:/driveLetter:/folderName/
or
Page 9
fmsadmin help close
fmsadmin help certificate
Usage: fmsadmin CLOSE [FILE...] [PATH...] [options]
Usage: fmsadmin CERTIFICATE CERT_OP [NAME] [FILE]
Description:
Closes the specified databases (FILE) or all the hosted
databases in the specified folders (PATH). If no FILE or
PATH is specified, closes all hosted databases.
Description:
This command lets the administrator manage SSL certificates.
To specify a database by its ID rather than its filename, first
use the LIST FILES -s command to get a list of databases
and their IDs.
CREATE Generate an SSL private key and a certificate
request to be sent to a certificate authority for signing.
Valid certificate operations (CERT_OP) are:
Options:
IMPORT
authority.
-m message, --message message
Specifies a text message to be sent to the clients that are
being disconnected.
For the CREATE operation, a unique NAME for the database
server is needed. This is in the form of server name or DNS
name, e.g.
-t seconds, --gracetime seconds
Specifies the total number of seconds to wait before forcing
disconnection of clients. The default (and minimum) value is
90 seconds.
fmsadmin certificate create myserver.filemaker.com
or
fmsadmin certificate create /CN=srvr.filemaker.com/C=US
-f, --force
Forces a database to be closed, immediately disconnecting
clients (overrides -t option).
Import an SSL certificate issued by a certificate
For the IMPORT operation, the full path of the signed certificate
FILE from the certificate authority is required, e.g.
fmsadmin certificate import /Downloads/Signed.cer
Options:
No command specific options.
Page 10
fmsadmin help disable
fmsadmin help disconnect
Usage: fmsadmin DISABLE SCHEDULE
[SCHEDULE_NUMBER]
Usage: fmsadmin DISCONNECT CLIENT [CLIENT_NUMBER]
[options]
Description:
Disables a schedule. SCHEDULE_NUMBER is the ID of the
schedule to disable. Use the LIST SCHEDULES command to
obtain the ID number of each schedule.
Description:
Disconnects the specified client. The CLIENT_NUMBER is the
ID number of the client. Use the LIST CLIENTS command to
obtain a list of clients and their ID numbers. If no
CLIENT_NUMBER is specified, all clients are disconnected.
Options:
No command specific options.
Options:
-m message, --message message
Specifies a text message to be sent to the client that is being
disconnected.
Page 11
fmsadmin help enable
fmsadmin help help
Usage: fmsadmin ENABLE SCHEDULE
[SCHEDULE_NUMBER]
Usage: fmsadmin [options] [COMMAND]
Description:
Enables a schedule. SCHEDULE_NUMBER is the ID of the
schedule to enable. Use the LIST SCHEDULES command to
obtain the ID numbers of each schedule.
Options:
No command specific options.
Description:
fmsadmin is the command line tool to administer the Database
Server component of FileMaker Server installed on the local
machine.
You can script many tasks with fmsadmin by using a scripting
language that allows execution of shell or terminal commands.
fmsadmin HELP COMMANDS
Lists available commands
fmsadmin HELP [COMMAND]
Displays help on the specified COMMAND
fmsadmin HELP OPTIONS
Lists available options
Also see "Command line reference" in FileMaker Server Help:
http://localhost:16000/admin-help/en
Page 12
fmsadmin help list
fmsadmin help open
Usage: fmsadmin LIST [TYPE] [options]
Usage: fmsadmin OPEN [FILE...] [PATH...]
Description:
Lists items of the specified TYPE.
Description:
Opens databases in the default and additional database
folders. Each FILE specified is opened, or all the databases in
each folder (PATH) are opened. If no FILE or PATH is
specified, all databases in the hosting area are opened.
Valid TYPES:
CLIENTS
FILES
Lists the connected clients.
Lists the hosted databases.
PLUGINS
SCHEDULES
To specify a database by its ID rather than its filename, first
use the LIST FILES -s command to get a list of databases and
their IDs.
Lists Database Server calculation plug-ins.
List schedules.
Options:
No command specific options.
Options:
-s, --stats
Reports additional details for each item.
Page 13
fmsadmin help pause
fmsadmin help remove
Usage: fmsadmin PAUSE [FILE...] [PATH...]
Usage: fmsadmin REMOVE [FILE...] [PATH...]
Description:
Pauses the specified databases (FILE) or all the hosted
databases in the specified folders (PATH). If no FILE or PATH
is specified, pauses all hosted databases.
After a database is paused, it is safe to copy or back up the
database until a RESUME command is performed.
Description:
Moves a database that has been closed into a "Removed"
folder so it will no longer be hosted. Each specified database
(FILE) is removed, and all databases in each folder (PATH)
are removed. If no FILE or PATH is specified, all closed
databases in the hosting area are removed. If a
specified folder (PATH) is empty, the folder will be removed.
Options:
No command specific options.
Options:
No command specific options.
Page 14
fmsadmin help restart
fmsadmin help resume
Usage: fmsadmin RESTART TYPE
Usage: fmsadmin RESUME [FILE...] [PATH...]
Description:
Restarts the server of specified TYPE. This command stops
the server TYPE and then starts it after a short delay.
Description:
Makes a database that has been paused available again.
Resumes activity on the specified databases (FILE) or all the
paused databases in the specified folders (PATH). If no FILE
or PATH is specified, all paused databases are resumed.
Valid TYPES:
ADMINSERVER
SERVER
Stops then starts the Admin Server.
Options:
No command specific options.
Stops then starts the Database Server.
This command works only if the FileMaker Server service
(Windows) or fmserver_helperd daemon (Mac OS) is running.
Options: (applicable to SERVER only)
-f, --force
Expedites shut down of the Database Server. All clients are
immediately disconnected.
-m message, --message message
Specifies a text message to send to the connected clients.
-t seconds, --gracetime seconds
Specifies the total number of seconds to wait before forcing
disconnection of clients.
Page 15
fmsadmin help run
fmsadmin help send
Usage: fmsadmin RUN SCHEDULE [SCHEDULE_NUMBER]
Usage: fmsadmin SEND [options] [CLIENT_NUMBER]
[FILE...] [PATH...]
Description:
Manually runs a schedule specified by its
SCHEDULE_NUMBER. To obtain a list of schedules and their
ID numbers, use the LIST SCHEDULES command.
Options:
No command specific options.
Description:
Sends a text message to a client specified by
CLIENT_NUMBER, to the clients connected to the specified
databases (FILE), or to all clients connected to any database
in the specified folders (PATH).
If no CLIENT_NUMBER, FILE, or PATH is specified, the
message is sent to all connected clients. By default,
parameters are expected to be FILEs or PATHs. To specify a
CLIENT_NUMBER, you must use the -c option. For example:
fmsadmin SEND -c 2 -m "This is a test message"
Options:
-m message, --message message
Specifies the text message to send.
-c, --client
Specifies a CLIENT_NUMBER.
Page 16
fmsadmin help start
fmsadmin help status
Usage: fmsadmin START TYPE
Usage: fmsadmin STATUS TYPE [CLIENT_NUMBER] [FILE]
Description:
Description:
Retrieves the status of the specified TYPE.
Starts the server of specified TYPE.
Valid TYPES:
Valid TYPES:
ADMINSERVER
SERVER
Starts the Admin Server.
Starts the Database Server.
This command works only if the FileMaker Server service
(Windows) or fmserver_helperd daemon (Mac OS) is running.
CLIENT
Retrieves the status of a client specified by
CLIENT_NUMBER.
FILE
FILE.
Retrieves the status of a database specified by
Options:
No command specific options.
Options:
No command specific options.
Page 17
fmsadmin help stop
Usage: fmsadmin STOP TYPE [options]
Description:
Stops the server of specified TYPE.
Valid TYPES:
ADMINSERVER
Stops the Admin Server.
SERVER
Stops the Database Server. By default, all
clients are disconnected after two minutes.
This command works only if the FileMaker Server service
(Windows) or fmserver_helperd daemon (Mac OS) is running.
Options: (applicable to SERVER only)
-f, --force
Expedites shut down of the Database Server. All clients are
immediately disconnected.
-m message, --message message
Specifies a text message to send to the connected clients.
-t seconds, --gracetime seconds
Specifies the total number of seconds to wait before forcing
disconnection of clients.
Page 18
fmsadmin help verify
Usage: fmsadmin VERIFY [FILE...] [PATH...] [options]
Description:
Closes the specified databases (FILE), or all the hosted
databases in the specified folders (PATH), then performs a
consistency check when reopening them. Databases that fail
the check are left closed. If no FILE or PATH is specified,
closes and checks all hosted databases.
Options:
-m message, --message message
Specifies a text message to be sent to the clients that are
being disconnected.
-t seconds, --gracetime seconds
Specifies the total number of seconds to wait before forcing
disconnection of clients. The default (and minimum) value is
120 seconds.
-f, --force
Forces a database to be closed without prompting clients.
Page 19