OVERVIEW
The FRP Web Services provide users with a scriptable interface to FRP. They are designed to be run from the command line, from user scripts or from web pages or as HTTP urls. An XML-RPC programmatic API is also supported.
Web Services and their associated FRP Command Line Interface utility are designed to assist you in the following situations:
• Define and immediately execute an FRP job from the command line.
• Define and store an FRP job from the command line.
• Import and export jobs in XML format.
• Activate and run stored jobs.
• Modify existing jobs
• Add servers to or remove servers from the FRP network configuration
SAMPLE SCENARIOS
- You need to copy a directory from server A to B so as to bring B up to date. Folders A and B might be quite large and may have many files that are either equal or almost equal. You simply want to take advantage of FRP's speed and sophisticated synchronization capabilities to perform the one-time copy straight from the command line.
- Rather than a copy as in the previous scenario you may want to newly copy a directory to another server, move a directory, or perform a one way mirror or a two way mirror between directories.
- Your company uses a central scheduler and you want to schedule FRP jobs via that tool rather than use the built in FRP scheduler.
- After successful completion of a production job, you want to copy some directories to another server. You want to add the FRP copy command to the post production script.
- You need FRP to collect data from one or more servers prior to starting a production job. You want to add that step to your pre production script.
- You want to maintain a script text file as the source of all the servers and jobs in your configuration. You feel it is easier to maintain that script, using copy and paste to handle multiple, similar jobs, and then submit it to FRP.
- You want to back up your FRP list of servers and/or jobs in a way that will let you import them later.
- You want to programmatically decide to start an existing FRP job.
- You want to allow a user to start a job (e.g. to back up his server data) by invoking this action from a web page you have created for him, without granting him access to the Management Server.
- You want to programmatically create or start jobs, but would prefer to use simple URLs rather than the more demanding XML-RPC API.
IMPLEMENTATION
The commands are implemented as Web Services. This implies that they can be invoked from any software that supports the web services interface. Additionally, two “clients” are provided by FRP.
FRPCLI – A FREE COMMAND LINE CLIENT
The command line client (FRPCLI) is automatically installed on every FRP server. Additionally, you can install FRPCLI on any computer (simply copy the FileReplicationPro/SDK/bin directory to the computer and run FRPCLI from that directory). This means that you can create new jobs from any server or desktop you designate, submit those jobs to the management server for storage and/or execution and then have their activation and execution managed like all other FRP jobs.
Refer to the FRPCLI Examples for command syntax
AN HTTP WEB PAGE CLIENT
An HTTP client page is included in the Management Server which receives the commands as HTTP GETs (i.e. as a URL where the parameters are the Query String) and convert them to service requests. The HTTP command syntax is the same as the command line syntax except that the “server” and server’s Ip address are not required since they are implied in the URL.
Please note that the commands for Job and Server Import/Export are not available in the Web page CLI or direct HTTP modes.
The client webpage can be accessed at: http://localhost:9100/cli_console.jsp
Refer to the CLI Console Examples for command syntax
DIRECT HTTP / HTTPS SUBMISSION VIA THE WEB
In the near future we will be releasing an upgrade which will permit the direct submission of commands to the management server via secure SSL with passwords. This feature will permit organizations to issue commands via the internet which originate from the output of scripts or batch functions to use any of the functions of the CLI system.
Please note that the commands for Job and Server Import/Export are not available in the Web page CLI or direct HTTP modes.
A sample command issued in this fashion will look like this:
https://123.x.x.1:9100/servlet/cli?param=copy //162.x.x.2/c:/data/docs //210.x.x.2/c:/backup/docs
Refer to the HTTP Examples for command syntax
API
A programmatic interface based on the web services XML-RPC interface is available. One approach is to generate a stub. A programmer can use a WSDL file with a service description, which is available at http://localhost:9100/services/FRPService?wsdl and then execute a tool which will generate stubs from the provided WSDL file. This approach works in .NET and other strong typed languages.For the dynamic approach developers can use http://server_address:9100/services/FRPService as the target URL and run RPC calls against it.
Every service request is forwarder to the central CLI service on the management server. Parsing and validation are performed by that service. The service returns a response object which contains “good result information” or error information. The thin clients are responsible for converting the response object to a format appropriate for the Post or the command line.
FRPCLI ACTION COMMAND LINE SYNTAX
FRPCLI server [server ip-address] action //server1/path //server2/path [run=now|hh:mm] [repeat=once|nh|nm|RT] [inactive] [makedir] [name=user-job-name]
Server When using the FRPCLI command line client, the server ip-address parameter identifies the location of the management server.
Action can be one of: copy, move, mirror1way, mirror2way, jobstart, jobdelete
Server1 is the source server, server2 is the destination. The server names are the server host names used by FRP (as in the server overview page). Note that when the path name includes spaces, the server and path are surrounded by double quotes (e.g. “//Chicago25/Users/Client Billing/Monthly Reports” )
Run = now will start the job immediately. Otherwise it will start at hh:mm (24 hour clock format). If omitted, the default is run=now.
Repeat = once indicates that after the first execution the job becomes inactive. This is the default. For any other ‘Repeat’ value, the job is repeatedly executed. For RT the execution is real time, for nh or nm the job is executed every n hours or minutes.
The inactive parameter lets you define a job for later activation.
The makedir parameter will instruct FRP to create the destination directory if not present. This is particularly useful when using FRPCLI as an advance network copy command.
The name parameter lets you name the job. No spaces are allowed in the name. The job is saved in the system. It is available to be started again or modified (either from the command line or the GUI) as any regular FRP job.
When an unnamed job is entered for immediate execution, FRP will assign the job a temporary name and the job will be considered transient. The job (and its logs) will be purged from the system immediately upon completion.
There are restrictions associated with transient jobs: a) No repeating schedule is allowed, i.e. Repeat must equal “once” and b) The inactive parameter cannot be used.
For a named job, FRP will overwrite an existing job. This allows you to modify an existing job.
Note that both, newly entered jobs and jobs modified through FRP Web Services, behave as if they were entered via the Management Console. This means that these jobs are saved by the Management Server and are automatically propagated to all relevant Replication Servers.
To immediately start an existing job, regardless of its run parameter, use the action verb jobstart and provide the name=jobname parameter.
To delete an existing job, use the action verb jobdelete and provide the name=jobname parameter.
ADD/REMOVE SERVERS
FRP Web Services can be used to add or remove servers.
To add a server, use the serveradd action. Specify the server address either as an ip address or a host name that will be resolved by your network. You can optionally specify a port number. The sever will be added and given a server-name (which is commonly the host name of that server with qualifiers removed).
To delete a server from the configuration use the serverdelete action followed by the serverName to be removed.
Examples:
frpcli server 192.168.2.1 serveradd 192.168.2.2
frpcli server 192.168.2.1 serverdelete 192.168.2.2
EXPORT/IMPORT COMMAND LINE OPTIONS
FRPCLI server [ip-address] Import Jobs|Servers xmlfile
Example: FRPCLI server 192.168.0.1 export servers serverlist.xml
Example: FRPCLI server 192.168.0.1 import jobs c:\ joblist.xml
The FRP Import command imports a list of jobs or servers from the xmlfile. In an error is encounterd the process may take a couple of minutes while validation is completed then any error will be output to the console or standard output.
For Example:
Unable to import one or more jobs, reason: Could not establish connection with SUPERUBUNTU. Job can not be validated. Read timed out
Export/import is NOT available thru HTTP. This command is only available in FRPCLI. The same job and server information exists on all servers in the FRP group, therefore it is only required to export or restore this information from the Management Server to preserve all the information for all servers.
The larger your FRP server group and the more jobs you have the more important it is for you to export the jobs and the servers when you have your configuration set and store the information in a safe place. This can be invaluable if you should loose your configuration for some reason.
TECHNICAL NOTE:
Following is some additional technical details regarding the XML processing.
For exported jobs, all the Connection objects are written. For exported servers, the LanMaster object is written.
Upon inport, some validation is performed and errors are written to standard output.
For servers, all three LanMaster header fields must be set to the correct LanID. If the LanID differs from the management server an error “LanID does not match Management Server” is issued and the load is aborted.
For each server (ComputerMaster), the ComputerID is checked against the current configuration and if it already exists, the imported object is skipped. Otherwise, the ComputerMaster object is added.
For each job, the ComputerA and B ID’s must be found in the current configuration. Otherwise an error is issued and the job is skipped. Next, the JobName is looked up (going through all current connection objects). If a JobName with matching ComputerA and B ID’s in the connection is found, it is replaced by the import. If the JobName is found but either ComputerA or B do not match, an error is issued and the job skipped. If the job name is not found, a new connection object is created.
No connection attempt is made during import.
FRPCLI USAGE EXAMPLES
In all the examples below we assume that the Management Server resides at 71.58.12.01 and that the commands are issued from any server running FRP . Notice that on a Mac or Linux servre you will need to observe two conventions: a) you must use two forward slashes (i.e. // ) before and after the server name or iP and b) While FRPCLI commands are not case sensitive, paths are. If there are spaces anywhere in the path you must enclose the path in quotes. For an example of this usage see example 4.
1. Perform an immediate two-way synchronization between 2 directories
FRPCLI server 71.58.12.01 mirror2way //WinLA/C:\Data\LA //OSXAtlanta/Documents/LA
to keep the job for later use you can add name=myLASync
2. Copy the Products directory from the NY to the LA server, create the directory in LA. This is to be run tonight at 11pm and every night thereafter :
FRPCLI server 71.58.12.01 copy //WinNY/C:\Data\Products //WinLAN/ C:\Data\Products run=23:00 Repeat=24h name=ProcudtsNY2LA makedir
If you want to copy the directory immediately and then have a nightly copy, simple precede the above command with:
FRPCLI server 71.58.12.01 copy //WinNY/C:\Data\Products //WinLAN/ C:\Data\Products makedir
3. You already have defined a job that copies the Products directory from the NY to the LA server every night at 11pm. The job name is ProductsNY2LA. To run this job now “out of schedule” use:
FRPCLI server 71.58.12.01 jobstart name=ProcudtsNY2LA4. You have a job to copy files from a windows machine to a Mac or Linux machine where the directory needs to be created. Remember the case sensitive path, double forward slashes and enclosing paths with embedded spaces with double quotes.
FRPCLI server 10.0.0.2 copy //newyork-windows7/c:\replicationtest "//Houston-MAC-PRO//Users/MacAdmin/Desktop/newfolder" name=MacJob2 makedir
5. Delete the New York to LA replication job named NYTOLA
FRPCLI SERVER 71.58.12.01 jobdelete name=NYTOLA
HTTP CLI WEB PAGE EXAMPLES
An HTTP client page is included in the Management Server which receives the commands as HTTP GETs (i.e. as a URL where the parameters are the Query String) and convert them to service requests. The HTTP command syntax is the same as the FRPCLI command line syntax except that the “server” and server’s Ip address are not required since they are implied in the URL.
A few examples are published below to demonstrate syntax, use any commands from the reference except import/export jobs/servers which can only be run in the FRPCLI
The client webpage can be accessed at: http://localhost:9100/cli_console.jsp
EXAMPLES:
mirror1way //newyork/c:\replicationtest //xpclone/c:\replicationtest2 name=hongkongsync makedir
mirror2way //newyork/c:\replicationtest //xpclone/c:\replication name=dallasclone
copy //newyork-windows7/c:\replicationtest "//Houston-MAC-PRO//Users/MacAdmin/Desktop/newfolder" name=MacJob2 makedir
jobstart name=dallasclone1
jobdelete name=NYTOLA
DIRECT HTTP SUBMISSION
Not implemented in version 5.6.0
FRP will accept the submission of commands by making a direct submission to the IP address of the Management Server from anywhere in the world. Provided the submission meets security requirements and authentication requirements.
The following special cases apply.
EXAMPLES: (HTTP or HTTPS)
Authentication parameters not yet published in this document.
https://71.58.12.01:9100/servlet/cli?param=copy //10.0.0.2/c:/replicationtest //10.0.0.2/c:/replicationtest1 makedir
http://localhost:9100/servlet/cli?param=copy //10.0.0.2/c:/replicationtest //10.0.0.2/c:/test
http://localhost:9100/servlet/cli?param=copy //10.0.0.2/c:/replicationtest //SARA-HONGKONG/c:/test makedir
http:// 71.58.12.01:9100/servlet/cli?param=copy //10.0.0.2/c:/replicationtest //SUPERUBUNTU//home/yitzi/Desktop/newer name=SuperUbuntu2 makedir
CONFIGURATION
The FRP administrator has the ability to enable/disable remote access, via either CLI or HTTP, XML-RPC programmatic access is not yet released .
Access is controlled through the property named 's2s.web_services' in s2s.properties file. This can be found in /FileReplicationPro/lib/s2s.properties the next line is the exact syntax for the switch where all Web services are enabled.
s2s.web_services=ALL | NO | CLI | HTTP
's2s.web_services' can be set to one of the above 4 values (case insensitive).
Setting the ALL value will enable both, CLI and HTTP access
Setting the NO value will disable both, CLI and HTTP access
Setting the value to CLI will enable CLI and disable HTTP
Setting the value to HTTP will allow HTTP and disable CLI access
If the web_services property is not present in the properties file (which is the default) it is set to CLI.