Skip to content

Update iRODS documentation to align with irods4j refactor #632

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
korydraughn wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update iRODS documentation to align with irods4j refactor #632

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d64597c
Update iRODS documentation to align with irods4j refactor
korydraughn Dec 9, 2025
d41ced9
squash. code review
korydraughn Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 124 additions & 26 deletions protocols/irods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
iRODS (Integrated Rule-Oriented Data System)
====

> The Integrated Rule-Oriented Data System (iRODS) is an open-source data management software used by research organizations and government agencies worldwide.
> The Integrated Rule-Oriented Data System (iRODS) is an open-source, policy-based data management software used by research, commercial, and governmental organizations worldwide.

:::{admonition} iRODS ...
:::{admonition} iRODS
:class: tip

- ... enables data discovery using a metadata catalog that describes every file, every directory, and every storage resource in the data grid.
- ... automates data workflows, with a rule engine that permits any action to be initiated by any trigger on any server or client in the grid.
- ... enables secure collaboration, so users only need to log in to their home grid to access data hosted on a remote grid.
- ... implement data virtualization, allowing access to distributed storage assets under a unified namespace, and freeing organizations from getting locked into single-vendor storage solutions.
- Enables data discovery using a metadata catalog that describes every file, every directory, and every storage resource in the data grid.
- Automates data workflows, with a rule engine that permits any action to be initiated by any trigger on any server or client in the grid.
- Enables secure collaboration, so users only need to log in to their home grid to access data hosted on a remote grid.
- Implements data virtualization, allowing access to distributed storage assets under a unified namespace, and freeing organizations from getting locked into single-vendor storage solutions.
:::

:::{important}
Requires iRODS 4.3.2 or newer.
:::

## Connecting
Expand All @@ -22,49 +26,143 @@ Connection profiles can be installed from *Preferences → Profiles*.

### Provider

- [CyVerse Data Store](http://www.cyverse.org/data-store) (Formerly iPlant Collaborative) - {download}`Connection Profile<https://profiles.cyberduck.io/iRODS%20(iPlant%20Collaborative).cyberduckprofile>`
- RENCI - {download}`Connection Profile<https://profiles.cyberduck.io/iRODS%20(RENCI).cyberduckprofile>`
- TACC - {download}`Connection Profile<https://profiles.cyberduck.io/iRODS%20(TACC).cyberduckprofile>`
A general purpose iRODS connection profile is available {download}`here<https://profiles.cyberduck.io/iRODS.cyberduckprofile>`.

All configuration properties described on this page are also documented in the connection profile.

### Authentication

#### Authentication With Native Scheme
#### Authentication with the Native scheme

This is the default with no additional configuration required.
To authenticate, set the **Authorization** value to `native` or `standard` in the [connection profile](index.md#connection-profiles). Defaults to `native`.

```
<key>Authorization</key>
<string>native</string>
```

`standard` is an alias for `native`. It is provided for backward compatibility.

#### Authentication with the PAM scheme

:::{note}
PAM requires a secure connection to the server. See [Secure Communication](#secure-communication) to learn more.
:::

To authenticate with PAM, set the **Authorization** value to `pam_password` or `pam` in the [connection profile](index.md#connection-profiles).

```
<key>Authorization</key>
<string>pam_password</string>
```

`pam` is an alias for `pam_password`. It is provided for backward compatibility.

#### Configuring the iRODS Zone

The zone of the target server must be specified before connecting to it. To do that, set the **Region** value in the [connection profile](index.md#connection-profiles).

```
<key>Region</key>
<string>zone_name</string>
```

#### Authentication With PAM Scheme
### Secure Communication

To authenticate with PAM, prefix the username with PAM:or set it in the [connection profile](index.md#connection-profiles) using as
To require secure communication, you must first set the **Client Server Negotiation** value to `CS_NEG_REQUIRE` in the [connection profile](index.md#connection-profiles).

```
<key>Authorization</key>
<string>PAM</string>
<key>Properties</key>
<dict>
<key>Client Server Negotiation</key>
<string>CS_NEG_REQUIRE</string>
</dict>
```

### Resource Server
Set the value to `CS_NEG_DONT_CARE` to let the server decide whether to use secure communication. Set it to `CS_NEG_REFUSE` to require an insecure channel. If the client and server cannot agree on how to proceed, the connection will fail and result in an error.

You can specify a non-default resource server in the Region key of the [connection profile](index.md#connection-profiles) using a colon-separated syntax (Issue [#8721](https://github.com/iterate-ch/cyberduck/issues/8721)) such as
Next, configure the encryption values to match those of the server. Consult the administrator of the iRODS zone to obtain the correct values.

```
<key>Region</key>
<string>iplant:storageresourcename</string>
<key>Properties</key>
<dict>
<key>Encryption Algorithm</key>
<string>AES-256-CBC</string>

<key>Encryption Key Size</key>
<string>32</string>

<key>Encryption Salt Size</key>
<string>8</string>

<key>Encryption Hash Rounds</key>
<string>16</string>
</dict>
```

#### Storage Resource

To upload files to a specific resource, set the **Destination Resource** value in the [connection profile](index.md#connection-profiles). The specified resource must be the root of a resource hierarchy. This property supersedes any resource defined by the **Region** property.

```
<key>Properties</key>
<dict>
<key>Destination Resource</key>
<string>resource_name</string>
</dict>
```

For backward compatibility, it can also be set by appending the name of the resource to the **Region**'s value. This method may be removed in the future.

```
<key>Region</key>
<string>zone_name:resource_name</string>
```

## Transfers

### Use Parallel Connections
### Parallel Transfer

Large file uploads will use parallel transfer when the requirements are satisfied. By default, a file must be larger than 32MB in order to trigger parallel transfer.

If [multiple connections](../cyberduck/transfer.md#connections) are configured by default in *Preferences* or set in the bookmark options with *Transfer Files: Open multiple connections*, get and put transfers to the data store use parallel concurrent connections.
The default values for parallel transfer are shown below. Descriptions of each property follow.

![Open multiple connections](_images/Use_parallel_transfer_option.png)
```
<key>Properties</key>
<dict>
<key>Parallel Transfer Threshold</key>
<string>33554432</string>

<key>Parallel Transfer Connections</key>
<string>3</string>

<key>Parallel Transfer Buffer Size</key>
<string>4194304</string>
</dict>
```

**Parallel Transfer Threshold** is the size (in bytes) of a file to upload that must be exceeded before parallel transfer is used. The value must satisfy the range [1, 2<sup>31</sup>-1].

The number of parallel connections is controlled using the lower right stepper control in the [Transfers](../cyberduck/transfer.md) window.
**Parallel Transfer Connections** is the number of connections used to upload a single file when parallel transfer is used. The value must satisfy the range [2, 10].

![Limit Number of Transfers](_images/Limit_Number_of_Transfers.png)
**Parallel Transfer Buffer Size** is the size (in bytes) of each buffer used to transfer bytes to the server. This property applies to uploads and downloads. The value must satisfy the range [1, 128MB].

### Trash Policy

To delete data objects and collections permanently, set the **Delete Objects Permanently** value to `yes` in the [connection profile](index.md#connection-profiles). Defaults to `no`.

```
<key>Properties</key>
<dict>
<key>Delete Objects Permanently</key>
<string>yes</string>
</dict>
```

## References

- [irods.org](http://irods.org/)
- [irods.org](https://irods.org/)
- [docs.irods.org](https://docs.irods.org/)
- [Downloading and Uploading Data](https://cyverse.atlassian.net/wiki/spaces/DS/pages/241869862/Downloading+and+Uploading+Data)
- [Using Cyberduck for Uploading and Downloading to the Data Store](https://cyverse.atlassian.net/wiki/spaces/DS/pages/241869843/Using+Cyberduck+for+Uploading+and+Downloading+to+the+Data+Store)
- [iRODS Error Events](https://github.com/irods/irods-legacy/blob/master/iRODS/lib/core/include/rodsErrorTable.h)
- [iRODS Error Codes](https://github.com/irods/irods/blob/main/lib/core/include/irods/rodsErrorTable.h)
Loading