iRODS Native Interface in Go

The iron utility is both a golang library and a command line client, that provides a clean, simple and stable interface to iRODS.

This documentation page contains all technical information about the library and contains only generic installation instructions. KU Leuven or VSC users should consult the RDM documentation pages instead for installation instructions. Users from other institutes should contact their respective support staff.

The CLI binary can be downloaded directly from https://github.com/kuleuven/iron/releases/latest. E.g. on a Linux system or Windows WSL:

VERSION=$(curl -Ls -w %{url_effective} -o /dev/null https://github.com/kuleuven/iron/releases/latest | sed 's/.*\/v//')
mkdir -p ~/.local/bin/
curl -L -s "https://github.com/kuleuven/iron/releases/download/v${VERSION}/iron_${VERSION}_linux_amd64.tar.gz" | tar zxvf - -C ~/.local/bin/

Alternatively, it can be installed with go install:

go install github.com/kuleuven/iron/cmd/iron@latest

Note that the released windows binaries are not signed. Windows users may alternatively use an installer for a signed iron.exe binary that we publish on https://icts-p-coz-iron-releases.cloud.icts.kuleuven.be/iron/. Linux users can find deb and rpm packages at the same location.

The CLI expects a ~.irods/irods_environment.json file being present, with native or pam_password authentication. The password should either be given in this file under the pam_password key, or the irods authentication file .irods/.irodsA must be present.

$ iron
Golang client for iRODS

Usage:
  iron [command]

Available Commands:
  checksum    Compute or get the checksum of a file
  chmod       Change permissions
  completion  Generate the autocompletion script for the specified shell
  cp          Copy a data object
  create      Create a data object
  download    Sync a collection to a local directory
  get         Download a file
  help        Help about any command
  inherit     Change permission inheritance
  ls          List a collection
  mkdir       Create a collection
  mv          Move a data object or collection
  put         Upload a file
  rm          Remove a data object or collection
  rmdir       Remove a collection
  shell       Start an interactive shell.
  stat        Get information about an object or collection
  tree        Print the full tree structure beneath a collection
  upload      Sync a local directory to a collection

Flags:
      --admin            Enable admin access
  -v, --debug count      Enable debug output
  -h, --help             help for iron
      --native           Use native protocol
      --workdir string   Working directory

Use "iron [command] --help" for more information about a command.
$ iron shell
iron > /set > ls
rods  0 B  Jul 07 18:31    home/
rods  0 B  Nov 11  2022    projects/
iron > /set > ls home/
rods          0 B  Jul 07 09:50     coz/
rods          0 B  Aug 08  2024     public/
set_demo      0 B  Feb 02 09:38  +  set_demo/
set_pilot013  0 B  Jan 01 19:02     set_pilot013/
iron > /set > cd home/coz/
iron > /set/home/coz > ls
peter  0 B     Jul 07 11:11     peter/
iron > /set/home/coz > ls peter
peter  0 B     Jul 07 11:11     peter.txt
iron > /set/home/coz > local pwd
/home/peter
iron > /set/home/coz > local cd sub
iron > /set/home/coz > local pwd
/home/peter/sub
iron > /set/home/coz > download peter localdir
localdir/peter.txt
iron > /set/home/coz > exit
$ ls /home/peter/sub/localdir
peter.txt

A Fyne-based desktop GUI is available as a separate project https://github.com/kuleuven/iron-gui. It reuses the same ~/.irods/irods_environment.json, .irodsA and .irodsA.json files as the CLI, supports pam_interactive authentication from a login form, and lets you browse collections, transfer files edit metadata/permissions, and compute checksums.

The GUI project should be considered as a Proof of Concept only at this time. For that reason, the source code is currently private, but binary releases are available at https://icts-p-coz-iron-releases.cloud.icts.kuleuven.be/iron/.

import (   
	"github.com/kuleuven/iron"
	"github.com/kuleuven/iron/api"
)

func example() error {
    var env iron.Env

    err := env.LoadFromFile(".irods/irods_environment.json")
    if err != nil {
        return err
    }

    env.Password = "my_password"

    ctx := context.Background()

    client, err := iron.New(ctx, env, iron.Option{
        ClientName:        "iron",
        Admin:             false, // Set to true to do all operations as admin, bypassing any ACLs
        MaxConns:          5,
    })
    if err != nil {
        return err
    }

    defer client.Close()

    objects, err := client.ListDataObjectsInCollection(ctx, "/path/to/data")
    if err != nil {
        return err
    }

    for _, object := range objects {
        fmt.Println(object.Path)
    }

    // Recursive walk through the tree, displaying access and metadata
    fn := func(path string, info api.Record, err error) error {
        if err != nil {
            return nil
        }

        fmt.Println(path)
        fmt.Printf("%v", info.Access())
        fmt.Printf("%v", info.Metadata())

        return nil
    }

    return client.Walk(ctx, "/path/to/more/data", fn, api.FetchAccess, api.FetchMetadata)
}

• The client currently requires 4.3.2 or later. We currently use it against 5.0.2 production services.
• New features might require a recent version of irods, i.e. support for older versions is not guaranteed.
• Breaking changes in further versions are avoided as much as possible, but the API might change in the future if it is beneficial.
• Simplified communication code: types of messages are defined in msg/types.go, and are marshaled using the right format (xml, json or binary) by msg.Marshal. The binary part (Bs) of messages is not marshaled by msg.Marshal/msg.Unmarshal but directly read or written to the provided buffers in msg.Read/msg.Write.
• Clients can choose between iron.Conn (one single connection) and iron.Client (a pool of connections) to use the provided API.
• The Truncate and Touch methods are only available on open file handles, to help identifying the right replica to adjust. Because irods only supports those operations when the file is closed, the operations are actually done on the replica when the file is closed.
• This client also attempts to support the native protocol, but this should be considered experimental.