Access Keys:
Skip to content (Access Key - 0)
In This Section

A Fabric Archive (FAR) is a versioned package containing a 3rd-party service, Java archive (JAR), .NET assembly, native code dynamic library (dll/so) or other support files that can be shared between several applications.

This package is deployed to a running fabric. Files listed in the FAR XML file will be available to any application that references the FAR. Java JARs listed in the 'java-libs' element will be seen by the application's Classloader. Native dynamic libraries listed in the 'libs' element will be loadable by the application. .NET assemblies listed in the 'assemblies' element will be copied to the base directory of their associated application and added to the probing path.

Applications and services can specify that they depend on a FAR and will be able to share access to the packaged files. Because the FAR is versioned, the FAR can be updated and deployed independently of the application. All files included by the FAR must be in the same directory as or a subdirectory of the FAR XML and the pathname must be a path relative to the FAR (e.g., './someDirectory/someLibrary.dll').

Download

Schemas and DTDs provide the syntax for acceptable XML files. However, there are additional semantic rules in place which affect packaging. Appistry highly recommends referencing the documentation while writing XML files.

Download eaf-far_v50.xsd.

far

The root element for the definition file is 'far'
Cardinality: 1...1 (i.e., required)

Attribute Use Description
name required The handle used by the Application XML. Simple Type:FabricIdentifier.
version required Deploying a FAR with an incremented version will result in that FAR file replacing previous versions on all nodes of the Fabric
display-name optional Used for display purposes only.
description optional Used for display/informational purposes only.

The 'far' element defines the following child elements (which can be included in any FAR):

Element Cardinality Description
java-libs 0...1 Java supported libraries (jars or zips) to be included in the FAR.
libs 0...1 Native code shared libraries (DLLs on Windows) to be included in the FAR.
assemblies 0...1 .NET assemblies that are to be included in the packaged FAR.
support-files 0...1 Miscellaneous files to be included in the FAR.
environment 0...1 Allows for the definition of OS-level environment variables.
variables 0...1 Allows the definition of XML-level variables.
console-extensions 0...1 URLs that will be added as tabs in the CloudIQ Platform Management Console.
Cardinality 0...1 The 'far' element allows an optional choice of one the following types of actionable elements (no choice is required)
Element   Description
installation   The installation tag should be used for archives and libraries that you want to install in specific places.
service   Scripts or executables and related command arguments required to start, stop, query or kill the service installed by FAR.
service-app   Identifies the service-application installed by FAR.
service-config   Identifies the service configuration file to be installed by FAR.

Sample FAR XML:

<?xml version="1.0"?>
<far name="deployable_misc_stuff" version="1.2.3">
   <java-libs>
      <file name="somejar.jar"/>
      <file name="some_subdir/someOtherJar.jar"/>
   </java-libs>
   <libs>
      <file name="some_dependency.dll"/>
      <file name="subdir/some_other_dependency.dll"/>
   </libs>
   <assemblies>
      <file name="some_assembly.dll"/>
      <file name="subdir/some_other_assembly.dll"/>
   </assemblies>
   <support-files>
      <file name="something.txt"/>
      <file name="subdir/foo.cfg"/>
   </support-files>
</far>
Executables

The FAR may execute files from any abosolute path or any path relative to 'FABRIC_HOME/fars/far-name', where 'far-name' is the 'name' attribute of the 'far' element.

FAR File Creation

After the FAR XML file has been created and the files are moved into the appropriate directory hierarchy, the deployable FAR file can be created with fabric_pkg. Once created, the .far file can be deployed using fabric_ctl command.

FAR Directory Management

It is the responsibility of the user to effectively manage their FAR directories. When a FAR is installed, the far is expanded into 'FABRIC_HOME/fars/far-name'. The files expanded into this directory are not deleted unless the the FAR is deleted. If a new version of the FAR is deployed over the top of an old one, corresponding files will be overwritten, however non-overlapping files will persist. Delete the old FAR prior to installation if you desire a cleaner directory.

java-libs

Contains a file list of Java supported libraries to be included in the FAR package. Any Java supported archive file can be listed here and will be visible to the user's Java code as if they were referenced by the CLASSPATH environment variable.
Cardinality: 0...1 (i.e., optional)

The 'java-libs' element defines a single child element:

Element Cardinality Description
file 1...n Java library file to be added to the package.

Sample 'java-libs' element: 

<java-libs>
   <file name="some_dependency.jar"/>
   <file name="subdir/some_other_dependency.jar"/>
</java-libs>

libs

Contains a file list for Windows DLLs and Linux shared objects (libraries) that are to be included in the FAR package. The runtime environment of Fabric applications that reference the FAR will be updated (i.e., the PATH environment variable on Windows and the LD_LIBRARY_PATH environment variable on Linux) with the containing directory of the library.
Cardinality: 0...1 (i.e., optional)

The 'libs' element defines a single child element:

Element Cardinality Description
file 1...n File to be added to the package and PATH/LD_LIBRARY_PATH.

Sample 'libs' element: 

<libs>
   <file name="some_dependency.dll"/>
   <file name="subdir/some_other_dependency.dll"/>
</libs>

assemblies

Contains a list of .NET assembly files that are to be included in the FAR package. The Fabric adds the directories containing the FAR assemblies to the probing path of the application's AppDomain, when it gets created.
Cardinality: 0...1 (i.e., optional)

The 'assemblies' element defines a single child element:

Element Cardinality Description
file 1...n Assembly file to be added to the FAR

Sample assemblies element: 

<assemblies>
   <file name="dotnet_assembly.dll"/>
   <file name="subdir/another_assembly.dll"/>
</assemblies>

support-files

Any files to be included in the deployable package. If required, include a configuration file (for example, settings.cfg) or any other files required by service. These files can be found on a worker at '$FABRIC_HOME/fars/far-name' where 'far-name' corresponds to the FAR's 'name' attribute. In the example, we include executables and scripts for installing, uninstalling and running the service, but these may also be found by relative path, absolute path or any available network path.
Cardinality: 0...1 (i.e., optional)

The 'support-files' element defines a single child type:

Element Cardinality Description
file 1...n Miscellaneous files to be added to the package. From within the Fabric, these files can be found by Fabric applications by prepending '../../fars/far-name' to the path of the file, where far-name is the FAR's name, as written in the FAR's name attribute.

Sample support-files element: 

<support-files>
   <file name="data_file.txt"/>
   <file name="subdir/other_data_file.dat"/>
   <file name="setup.exe"/>
   <file name="uninstall.exe"/>
</support-files>

console-extensions

Contains information about a web resource that will included in the CloudIQ Management Console or returned using the Management API.
Cardinality: 0...1 (i.e., optional)

The console-extensions element defines a single child element:

Element Cardinality Description
console-extension 1...n Extension URL to be added to the CloudIQ Platform Management Console.
Attribute Use Description
name required The short-name for the console-extension. SimpleType: FabricIdentifier
display-name optional The diplay name for the console-extension. Defaults to 'name'.
description optional A description of the extension being added.
type optional 'default' will place the extension as a tab on the main page. 'worker' will attach the extension to the worker-view. SimpleType: ExtensionMenuType
url required The URL for the console-extension. When 'type="default"', the fabric's CloudIQ Console will replace '%HTTP_ADMIN_IP%' in the URL with the IP address of the connected worker. When 'type="worker"', the console will replace '%WORKER_IP%' in the URL with the IP address for any given worker. This allows the addition of cutom web pages for each individual worker (displaying, for example, health monitoring). SimpleType: UrlString
icon-url optional The URL to the 'favicon' to be used with the extension. SimpleType: UrlString

Sample 'console-extensions' element: 

<console-extensions>
   <console-extension name="google" 
                      url="http://www.google.com" 
                      icon-url="http://www.google.com/favicon.ico"/>
   <console-extension name="Management Interface" 
                      type="default" 
                      url="http://%HTTP_ADMIN_IP%:80" />
   <console-extension name="Application Health" 
                      type="worker" 
                      url="http://%WORKER_IP%:80/app/healthtest.html" />
</console-extensions>

Simple Type Declarations

Name Restriction Pattern Description
FabricIdentifier token [A-Za-z0-9-_]+

The FabricIdentifier is a unique name (or ID) given to an item in its definition XML. It is an arbitrarily long, case sensitive sequence of one or more alphanumeric characters (upper or lower case), hyphens and underscores. Pattern:[A-Za-z0-9-_]+
RightsIdentifier token 'Elevated' or 'Default'

The 'RightsIdentifier' allows for the specification of system-level permission for the installation and/or execution of a FAR. The 'default' setting runs as 'fabricuser', the account under which the platform typically operates. The 'elevated' runs under the permissions granted to 'Fabric System Service (fabric_system_service)', which is typically 'root' on Linux and "local system" on Windows. In Windows, right-click on the 'Appistry System Service', click 'Properties', and select the 'Log On' tab. Select the 'This account:' radio button and enter the account information for the elevated rights.
ExtensionMenuType token 'worker' or 'default'

The 'ExtensionMenuType' identifies whether a 'console-extension' is a fabric-level or worker-level extension. This will impact the location the extension is embedded within the the CloudIQ Console.
UrlString token [A-Za-z0-9-_:/%\.]+

The 'UrlString' type accepts the common HTTP string characters: [A-Za-z0-9-_:/%\.]+
file

The listing for a single file in the FAR definition.
Cardinality: 1...n (i.e., one is required if parent is declared, many may be defined)

Attribute Use Description
name required Absolute or relative path to file, including file name and extension

Example 'file' sub-element:

<file name="some_dependency.dll"/>