RemoteClusterAccess

Connect to schedulers when client utilities are not available locally

Constructor

r = parallel.cluster.RemoteClusterAccess(username)

r = parallel.cluster.RemoteClusterAccess(username,P1,V1,...,Pn,Vn)

Description

r = parallel.cluster.RemoteClusterAccess(username) creates a RemoteClusterAccess object with the Username set to username.

By default, you are prompted for a password when you connect to the cluster.

Tip

If you have set up a cluster profile for a remote cluster, use parcluster. For more information, see Discover Clusters and Use Cluster Profiles.

You only need to use RemoteClusterAccess directly if you need to modify plugin scripts for third-party schedulers that do not have a built-in cluster type. You use plugin scripts when you connect to a cluster using the Generic scheduler interface. For more information, see Configure Using the Generic Scheduler Interface (MATLAB Parallel Server).

Use RemoteClusterAccess when you need to modify settings for remote cluster connection, submission, or data transfer.

r = parallel.cluster.RemoteClusterAccess(___,Name,Value) creates a RemoteClusterAccess object using one or more name-value arguments. For example, specify 'Port',31415 to connect to a cluster using port number 31415. Specify name-value arguments after all other input arguments.

The accepted name-value arguments are:

'AuthenticationMode' — Authentication mode you use when you connect to the cluster, specified as a string scalar, character vector, string array or cell array.
If you specify the argument 'IdentityFilename', the default value is 'IdentityFile'. Otherwise, the default value is 'Password'. Valid values for 'AuthenticationMode' are:
- 'Agent' – the client interfaces with an SSH agent running on the client machine.
- 'IdentityFile' – the client uses an identity file to authenticate when you connect to the cluster. If you specify a file using the IdentityFilename option, you use that file. Otherwise, MATLAB^® prompts you to specify the full path to an identity file when you connect.
- 'Multifactor' – the client prompts you for input one or more times. For example, if two-factor authentication (2FA) is enabled on the client, the client requests your password and a response for the second authentication factor.
- 'Password' – the client prompts you for your SSH password. Your user name is specified by the Username property.
Alternatively, to connect to a client with multiple authentication requirements, specify AuthenticationMode as a string array or cell array containing a combination of 'Agent', 'IdentityFile', 'Multifactor' and 'Password'.
'IdentityFileHasPassphrase' — Flag indicating if the identity file requires a passphrase, specified as true or false. If true, you are prompted for a password when you connect. If an identity file is not supplied, this name-value argument is not used.
'IdentityFilename' — Full path to the identity file to use when RemoteClusterAccess connects to a remote host, specified as 'IdentityFilename' and a string scalar or character vector.
'Port' — Port number on the cluster you connect to, specified as an integer scalar between 1 and 65535.
The default value is 22.

For more information and detailed examples, see Submit from a Remote Host (MATLAB Parallel Server) and Submit Without a Shared File System (MATLAB Parallel Server).

Methods

Method Name	Description
`connect`	`connect(r,clusterHost)` establishes a connection to the specified host using the user credential options supplied in the constructor. File mirroring is not supported. `clusterHost` must run Linux. `connect(r,clusterHost,remoteDataLocation)` establishes a connection to the specified host using the user credential options supplied in the constructor. `remoteDataLocation` identifies a folder on the `clusterHost` that is used for file mirroring. The user credentials supplied in the constructor must have write access to this folder.
`disconnect`	`disconnect(r)` disconnects the existing remote connection. The `connect` method must have already been called.
`doLastMirrorForJob`	`doLastMirrorForJob(r,job)` performs a final copy of changed files from the remote `remoteDataLocation` to the local `JobStorageLocation` for the supplied job. Any running mirrors for the job also stop and the job files are removed from the remote `remoteDataLocation`. The `startMirrorForJob` or `resumeMirrorForJob` method must have already been called.
`getRemoteJobLocation`	`getRemoteJobLocation(r,jobID,remoteOS)` returns the full path to the remote job location for the supplied `jobID`. Valid values for `remoteOS` are `'pc'` and `'unix'`.
`isJobUsingConnection`	`isJobUsingConnection(r,jobID)` returns `true` if the job is currently being mirrored.
`reconnect`	`reconnect(r)` recreates the existing SSH connections to the remote host.
`resumeMirrorForJob`	`resumeMirrorForJob(r,job)` resumes the mirroring of files from the remote `remoteDataLocation` to the local `JobStoragelocation` for the supplied job. This is similar to the `startMirrorForJob` method, but does not first copy the files from the local `JobStorageLocation` to the remote `remoteDataLocation`. The `connect` method must have already been called. This is useful if the original client MATLAB session has ended, and you are accessing the same files from a new client session.
`runCommand`	`[status,result] = runCommand(r,command)` runs the supplied command on the remote host and returns the resulting status and standard output. The `connect` method must have already been called.
`startMirrorForJob`	`startMirrorForJob(r,job)` copies all the job files from the local `JobStorageLocation` to the remote `remoteDataLocation`, and starts mirroring files so that any changes to the files in the remote `remoteDataLocation` are copied back to the local `JobStorageLocation`. The `connect` method must have already been called.
`stopMirrorForJob`	`stopMirrorForJob(r,job)` immediately stops the mirroring of files from the remote `remoteDataLocation` to the local `JobStorageLocation` for the specified job. The `startMirrorForJob` or `resumeMirrorForJob` method must have already been called. This cancels the running mirror and removes the files for the job from the remote location. This is similar to `doLastMirrorForJob`, except that `stopMirrorForJob` makes no attempt to ensure that the local job files are up to date. For normal mirror stoppage, use `doLastMirrorForJob`.
`getConnectedAccess`	`getConnectedAccess(host,username)` returns a `RemoteClusterAccess` object that is connected to the supplied host. This function may return a previously constructed `RemoteClusterAccess` object if one exists. `host` must run Linux. `getConnectedAccess(...,P1,V1,...Pn,Vn)` passes the additional parameters to the `RemoteClusterAccess` constructor.
`getConnectedAccessWithMirror`	`getConnectedAccessWithMirror(host,remoteDataLocation,username)` returns a `RemoteClusterAccess` object that is connected to the supplied host, using `remoteDataLocation` as the mirror location. This function may return a previously constructed `RemoteClusterAccess` object if one exists. `host` must run Linux. `getConnectedAccessWithMirror(...,P1,V1,...Pn,Vn)` passes the additional parameters to the `RemoteClusterAccess` constructor.

Properties

A RemoteClusterAccess object has the following read-only properties. Their values are set when you construct the object or call its connect method.

Property Name	Description
`AuthenticationMode`	Option indicating how you are authenticated when you connect to the cluster, returned as one of the following: `'Agent'` – the client interfaces with an SSH agent running on the client machine. SSH Agent authentication does not support keys in PPK format. Only keys in OpenSSH format are supported. `'IdentityFile'` – the client uses an identity file to authenticate when you connect to the cluster. If the `IdentityFilename` property is not an empty string or empty character vector, you use that file. Otherwise, MATLAB prompts you to specify the full path to an identity file when you connect. `"Multifactor"` – the client prompts you for input one or more times. For example, if two-factor authentication (2FA) is enabled on the client, the client requests your password and a response for the second authentication factor. `'Password'` – the client prompts you for your SSH password. Your user name is specified by the `Username` property. Array containing a combination of `'Agent'`, `'IdentityFile'`, `'Multifactor'` and `'Password'` - the client uses multiple authentication options to authenticate when you connect to the cluster. If the `IdentityFilename` property is not an empty string scalar or empty character vector, this property is set to `'IdentityFile'` by default. Otherwise, it is set to `'Password'` by default. To set this property, specify the `'AuthenticationMode'` name-value argument when you create a `RemoteClusterAccess` object.
`AutoReconnect`	Flag indicating if MATLAB automatically recreates the SSH connection to the remote host after a remote command errors, specified as `true` or `false`. The default value is `true`.
`Hostname`	Name of the remote host to access, returned as a character vector. The default value is an empty character vector.
`IdentityFileHasPassphrase`	Flag indicating if the identity file requires a passphrase, specified as the comma-separated pair consisting of `'IdentityFileHasPassphrase'` and `true` or `false`. The default value is `false`. If this property is set to `true`, you are prompted for a password when you connect. If an identity file is not supplied, this property is not used. To set this property, specify the `'IdentityFileHasPassphrase'` name-value argument when you create a `RemoteClusterAccess` object.
`IdentityFilename`	Full path to the identity file to use when the `RemoteClusterAccess` object connects to a remote host, returned as a character vector. The default value is an empty character vector. If this property is empty, you are prompted for a password when you connect. To set this property, specify the `'IdentityFilename'` name-value argument when you create a `RemoteClusterAccess` object.
`IsConnected`	Flag indicating if the `RemoteClusterAccess` object is connected to the cluster, returned as `true` or `false`. The default value is `false`.
`IsFileMirrorSupported`	Flag indicating if file mirroring is supported for the `RemoteClusterAccess` object, specified as `true` or `false`. The default value is `false`. The `IsFileMirrorSupported` property is set to `true` if the `JobStorageLocation` property is not empty.
`JobStorageLocation`	Location on the remote host for files that are being mirrored, returned as a character vector. The default value is an empty character vector. To set this property, use any of the following syntaxes to connect to the cluster: `connect(r,clusterHost,remoteDataLocation)` `r = getConnectedAccessWithMirror(host,remoteDataLocation,username)` `r = getConnectedAccessWithMirror(___,P1,V1,...Pn,Vn)`
`Port`	Port number you use to connect to the cluster, returned as an integer scalar between `1` and `65535`. The default value is `22`. To set this property, specify the `'Port'` name-value argument when you create a `RemoteClusterAccess` object.
`UseIdentityFile`	Flag indicating if the `RemoteClusterAccess`object uses an identity file to connect to the cluster, returned as `true` or `false`. The default value is `false`. If the `AuthenticationMode` property is `'IdentityFile'`, the `UseIdentityFile` property is `true`.
`Username`	User name you use to connect to the cluster, returned as a character vector.

Examples

Mirror files from the remote data location. Assume the object job represents a job on your generic scheduler.

remoteConnection = parallel.cluster.RemoteClusterAccess('testname');
connect(remoteConnection,'headnode1','/tmp/filemirror');
startMirrorForJob(remoteConnection,job);
submit(job)
% Wait for the job to finish
wait(job);

% Ensure that all the local files are up to date, and remove the 
% remote files
doLastMirrorForJob(remoteConnection,job);

% Get the output arguments for the job
results = fetchOutputs(job)

For more information and examples, see Submit from a Remote Host (MATLAB Parallel Server) and Submit Without a Shared File System (MATLAB Parallel Server).

Version History

Introduced in R2011a