Chapter 25. FileMaker Server Command-Line Reference
In addition to administering FileMaker Server using the FileMaker Server Admin Console, you also are able to administer the server using a command-line tool called fmsadmin. The fmsadmin tool is installed along with FileMaker Server itself and can be used to administer instances of FileMaker Server running on the same machine.
Administering FileMaker Server from the Command Line
The fmsadmin tool behaves like any other command-line utility or tool in the Mac OS X or Windows operating systems. You can invoke it directly from the command line (Mac OS X Terminal, Windows Command Prompt). You also can invoke it from within any command-line script, and as such, it can form part of a variety of automated administrative processes.
To invoke fmsadmin from the command line, you need to know where the tool is located. As long as the install location is in your system path, simply issuing the command fmsadmin (plus necessary options) is sufficient. The default install locations are as follows:
Mac OS X:
/Library/FileMaker Server/Database Server/bin/fmsadmin
Windows:
C:Program FilesFileMakerFileMaker ServerDatabase Serverfmsadmin.exe
On Mac OS X, a symbolic link to fmsadmin is created within /usr/bin, which is in the default system path, so you should be able to invoke it without any additional configuration. On Windows, you either need to reference it by using the full install path or add C: Program FilesFileMakerFileMaker ServerDatabase Server to your system path.
To issue instructions to FileMaker Server from the command line, you need to supply two pieces of information:
• The name of the tool itself (fmsadmin, assuming it is accessible by an existing path; otherwise, you must specify the full path to the tool).
• The name of a particular command to invoke, such as backup to back up files or close to close files.
You will generally also need one or more options that give further specificity to the command. Following is one example:
fmsadmin close –m "All files closing" –t 120
This command closes all files on the server after a two-minute (120-second) grace period and sends all connected clients a message saying “All files closing.”
Four general parameters can be specified for any command:
• -p pass, --password pass—Password to use to authenticate with the server.
• -u user, --user user—Username to use to authenticate with the server.
• -w seconds, --wait seconds—Specify time in seconds for the command to time out.
• –y, --yes—Automatically answer yes to all command prompts.
If you do not specify these parameters explicitly as part of the command syntax, you are asked to do so after submitting the command. All options have both a short form and long form. The short form requires a single hyphen and a one-character command; a space is optional between the option character and the parameter. The long option requires two hyphens and increases readability; a space is required between the option and its parameter. The following two commands are exactly the same: The first uses the short-form syntax; and the second, the long-form syntax.
fmsadmin send -c 17 -m "Fred, it's time to go home!"
fmsadmin send --client 17 --message "Fred, it's time to go home!"
If a parameter such as a filename, path, or message contains a space, enclose the parameter in single or double quotation marks.
FileMaker Server Command-Line Reference
The reference that follows includes the name of each command, along with a description, a general usage template, one or more examples, and explanations of any applicable options. Some of the options are specific to only one or two commands, but most are applicable across several commands.
See Chapter 21, “FileMaker Error Codes,” for a list of the errors that might be returned when issuing command-line instructions.
Options:
• ON—Turns on autorestart.
• OFF—Turns off autorestart.
Description:
By default, the autorestart setting is ON, which means that FileMaker Server automatically restarts the Admin Server process when it has stopped or is not responding for more than 60 seconds. This requires that the FileMaker Server service (Windows) or fmserver_helperd daemon (Mac OS) is running.
FileMaker Server stops monitoring the process if you stop the Admin Server by using the fmsadmin stop adminserver command.
If you omit the ON/OFF flag, the command returns the current autorestart setting.
fmsadmin autorestart adminserver on
fmsadmin autorestart adminserver off
Options:
• -d PATH, --dest PATH—Specify a destination path for a backup. The path to a folder must end with a slash (/) character.
• -k count, --keep count—Specify count of backups to keep (the default is 1).
• -n, --clone—Create a clone of each file (after verify, if that option is also specified).
• -x, --verify—Verify the integrity of each backup file.
Description:
The backup command can be used to back up a single specified file, all the files in a directory, or all the files hosted by a single instance of FileMaker Server. If no destination path is specified, the backup is created in the directory specified by the Default Backup Folder preference.
The backup command can be used alone, in which case it performs a “live” or “hot” backup of the specified files. It can also be used in conjunction with the pause and resume commands.
You can specify options that verify and clone the backup files after they have been backed up. The clones are created in the same destination folder as the backups, but in their own easily recognizable subdirectory.
If the --keep option is greater than zero, FileMaker Server creates a timestamped backup folder in the destination folder, and up to that number of backup folders are kept (disk space permitting). If the count is zero, the backup files are written directly to the destination folder, overwriting any existing files of the same name.
fmsadmin backup Products.fmp12 –u admin –p snoopy –k 2
fmsadmin backup -d "E:FileMaker Backups"
fmsadmin backup "filemac:/Server HD/Library/FileMaker Server/Data/Databases/InventoryFiles/" -x
Options:
• server_name—Specifies the hostname used by clients to access FileMaker Server.
• certificate_file—Indicates the full pathname to the signed certificate you have received from a certificate authority.
Description:
FileMaker Server, by default, provides an SSL certificate that does not require server name verification. As an additional security measure, you can request a signed certificate from a certificate authority that matches your specific server name or DNS name.
You can use the certificate create command to generate the request file that you send to the certificate authority (serverRequest.pem). It also generates an encrypted private key file (serverKey.pem) that the certificate import command uses.
You receive a certificate file from the certificate authority; you can use the certificate import command to create a file called serverCustom.pem that combines this certificate with the encrypted private key created by the certificate create command. This file is created in the FileMaker Server/Data/CStore/ directory.
After using the certificate import command, you must restart the Database Server.
fmsadmin certificate create athena.soliantconsulting.com
fmsadmin certificate import c:DocumentssignedCertificate.x509
Options:
• -f, --force—Force the file to be closed without a prompt for confirmation.
• -m message, --message message—Specify a text message to send to clients.
• -t seconds, --gracetime seconds—Specify time in seconds before clients are forcibly disconnected. The default (and minimum) is 120 seconds.
Description:
The close command closes one or more database files. It can be used to close a specific file, all the files in a directory, or all files on the server (if no file or path is specified). You can reference a file by its ID or its filename; use the command fmsadmin list files -s to get a list of files with their IDs.
fmsadmin close
fmsadmin close 3 15 16 -y
fmsadmin close -y Products.fmp12
fmsadmin close "Invoice Items.fp7" –y –u admin –p snoopy –m "Closing the database for a while!"
Options:
None
Description:
The disable command is used to disable schedules. Schedules must be referenced by number, which you can determine by using the fmsadmin list schedules command.
Options:
• -m message, --message message—Specify a text message to send to clients.
Description:
The disconnect command is used to disconnect a specific client. Clients must be referenced by client number, which you can determine by using the fmsadmin list clients command. A specific message also can be sent to the client(s).
If no client number is provided, all clients are disconnected.
fmsadmin disconnect client 13 –u admin –p snoopy -y
fmsadmin disconnect client 12 -m "It's time for lunch, Sara" -y
Options:
None
Description:
The enable command is used to enable schedules. Schedules are referenced by number, which you can determine by using the fmsadmin list schedules command.
Options:
None
The help command displays help information on the command-line commands and syntax. You can get help for a specific command by using the syntax fmsadmin help [command].
Options:
• -s, --stats—Return additional detail about clients or files.
Description:
The list command can be used to obtain a list of clients, files, plug-ins, or schedules from the server. Among other things, this command returns ID numbers that are necessary for other commands such as enable schedule and similar commands.
fmsadmin list clients -s –u admin –p snoopy
fmsadmin list schedules
fmsadmin list files --s
fmsadmin list plugins
Options:
None
Description:
The open command is used to open databases. Like the close command, it can be used to open all files on the server, all files within a single directory, or a single named file. If no file or directory is specified, the open command opens all database files in the default and additional database folders.
You can reference a file by its ID rather than its filename; use the command fmsadmin list files -s to get a list of files with their IDs.
fmsadmin open Clinic.fmp12
fmsadmin open -y
fmsadmin open 3 18 34 –u admin –p snoopy
fmsadmin open "filemac:/Library/FileMaker Server/Data/Databases/mySolution"
Options:
None
Description:
The pause command is used to pause databases. Like the open and close commands, it can be used to affect all files on the server, all files within a single directory, or a single named file.
You can reference a file by its ID rather than its filename; use the command fmsadmin list files to get a list of files with their IDs.
Options:
None
Description:
The remove command is used to remove a closed file from hosting. Note that database(s) must be closed prior to removing them. If you do not specify a file or path, all databases are removed from hosting.
Removed files are placed in a Removed directory within the Databases folder.
fmsadmin remove "Invoice Items.fmp12" –u admin –p snoopy
fmsadmin remove Products.fmp12 -y
Options:
• -f, --force—Shuts down the Database Server without waiting for clients to disconnect gracefully.
• -m message, --message message—Specify a text message to send to clients.
• -t seconds, --gracetime seconds—Specify time in seconds before clients will be are forcibly disconnected. The default (and minimum) is 120 seconds.
Description:
The restart command instructs the specified server or process to restart. The options are applicable only to stopping the Database Server, and the command works only if the FileMaker Server service (Windows) or the fmserver_helperd daemon (Mac OS) is running.
Valid types include the following:
• adminserver—Stops the Admin Server
• fmse—Stops the FileMaker Script engine
• server—Stops the Database Server
• wpe—Stops the Web Publishing Engine
• xdbc—Stops the XDBC listener
Options:
None
Description:
The resume command is used to resume databases that have been paused. Like the open and close commands, it can be used to affect all files on the server, all files within a single directory, or a single named file.
You can reference a file by its ID rather than its filename; use the command fmsadmin list files to get a list of files with their IDs. If no files are referenced, all databases are resumed.
fmsadmin resume 14 18 –u admin –p snoopy
fmsadmin resume Clinic.fmp12
Options:
None
Description:
The run command is used to run a schedule, specified by number. You can obtain schedule numbers by using the list schedules command.
fmsadmin run schedule 3
fmsadmin run schedule 12 –u admin –p snoopy
Options:
• -c, --client—Enable you to specify a client number.
• -m message, --message message—Specify a text message to send to clients.
Description:
The send command can be used to send a text message to the specified clients. Messages can be sent to all clients connected to the server, or they can be limited to just those clients connected to files in a specific path, to a single specific file, or to a single client specified by number. You must use the -c option when specifying a client number.
fmsadmin send -m "The server will shut down for maintenance in 15 minutes."
fmsadmin send -c 17 -m "Fred, it's time to go home!"
fmsadmin send "Clinics.fmp12" -m "The Clinics file will shut down in 5 minutes."
Options:
None
The start command instructs the specified server or process to start. It works only if the FileMaker Server service (Windows) or the fmserver_helperd daemon (Mac OS) is running.
Valid types include the following:
• adminserver—Starts the Admin Server
• fmse—Starts the FileMaker Script engine
• server—Starts the Database Server
• wpe—Starts the Web Publishing Engine
• xdbc—Starts the XDBC listener
Options:
None
Description:
The status command is used to determine the status of a client or a file.
fmsadmin status file "Invoice Items.fmp12"
fmsadmin status client 30
Options:
• -f, --force—Shut down the Database Server without waiting for clients to disconnect gracefully.
• -m message, --message message—Specify a text message to send to clients.
• -t seconds, --gracetime seconds—Specify time in seconds before clients are forcibly disconnected. The default (and minimum) is 90 seconds.
The stop command instructs the specified server or process to stop. The options are applicable only to stopping the Database Server.
Valid types include the following:
• adminserver—Stops the Admin Server
• fmse—Stops the FileMaker Script engine
• server—Stops the Database Server
• wpe—Stops the Web Publishing Engine
• xdbc—Stops the XDBC listener
fmsadmin stop wpe
fmsadmin stop server –t 120 –m "The server will shut down in two minutes."
fmsadmin stop fmse
Options:
• -f, --force—Close databases or shut down the server forcefully without waiting for clients to disconnect gracefully.
• -m message, --message message—Specify a text message to send to clients.
• -t seconds, --gracetime seconds—Specify time in seconds before clients are forcibly disconnected.
Description:
The verify command closes the specified database(s) and then performs a consistency check as it reopens them. If a database fails the consistency check, it does not reopen. If you do not specify any file or path, all databases on the server are verified.
If the file reopens, then it has passed the verification. You can confirm this by looking at Server Events in the Log Viewer in the Admin Console.
fmsadmin verify myDatabase.fmp12 –m "The database will be unavailable for a few minutes"
fmsadmin verify –u fred –p myPassword