Main Content

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 if you need to modify plugin scripts for third-party schedulers that you connect to in nonshared or remote submission mode. You use plugin scripts when you connect to a cluster using the Generic scheduler interface.

If the client is not able to submit directly to the third-party scheduler, or the client does not share a file system with the cluster, consider the following:

  • If the third-party scheduler has a MathWorks® add-on, install it. When you use an add-on, you can set up your cluster profile using the set-up wizard or the Cluster Profile Manager to set many settings. For more information, see Plugin Scripts for Generic Schedulers.

  • If you need to use a third-party scheduler that does not have an add-on, or if you need to customize an add-on, 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 Submitting from a Remote Host and Submitting Without a Shared File System.

Methods

Method NameDescription
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.

disconnectdisconnect(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.

reconnectreconnect(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 NameDescription
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.

  • '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 remove 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 RemoteClusterAccessobject 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 Submitting from a Remote Host and Submitting Without a Shared File System.

Version History

Introduced in R2011a