---
name: "dacsrlink"
section: "1"
platform: "linux"
package: "dacs"
version: "1.4.40-2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/dacsrlink"
---

# dacsrlink(1)

create and administer rule links

## NAME

dacsrlink - create and administer rule links

## SYNOPSIS

**dacsrlink** \[**dacsoptions**\[1\]\] *op* \[*arg*...\]

## DESCRIPTION

This program is part of the **DACS** suite.

The **dacsrlink** command is used to create and manage specially constructed URLs called Rlinks (*rule links*). Briefly, an Rlink is a URL that includes a special component called an Rname. The Rname identifies a specific **DACS** access control rule that is to be used with the URL, disabling the usual ACL searching algorithm for the request. Although no searching for the rule is done, the named ACL must still exist and match the request, such as through a suitable url\_pattern. As with any access control rule, arbitrary expressions can be evaluated before access to the URL is allowed (or denied), including client redirection.

An Rlink is handled by **[dacs\_acs(8)](/dacs_acs/8.md)**\[2\] during authorization checking. Because ACL searching is not performed for the request, Rlink processing can be more efficient. While the syntax of these rules is identical to that of normal access rules (**acl.dtd**\[3\]), not administered by **[dacsacl(1)](/dacsacl/1.md)**\[4\] and they are not indexed.

A given resource may be referenced by Rlinks with different Rnames. Each instance of an Rlink for the resource may therefore have different access rights or cause different side effects. Depending on the application, the creator of an Rlink may expect it to be kept secret by everyone that receives it, resulting in a weak (though often sufficient) method of access control.

There are many applications of Rlinks. They can be used to provide:

• identity-restricted access to a resource without having to create per-identity accounts; when the Rlink is invoked (optionally accompanied by a password bound to the URL), the identity is available to the access control rule and an invoked web service just as if "real" **DACS** credentials had been used;

• a convenient, user-friendly acknowledgement mechanism that has a weak degree of security; e.g., by creating a link that a user can click on to continue an account registration step or confirm reading a licensing agreement;

• a link that can be used for user tracking;

• a way to override or customize another rule without modifying the original rule;

• access to a resource with per-user constraints; e.g., to restrict access to a file or application for a particular user to a given time, date, or duration;

• a simple front end for creating ordinary access control rules.

A **DACS** identity may be attached to an Rlink through the command's rlink and rname operations. When an Rlink with an attached identity is used, that identity is available to **dacs\_acs**\[2\] for access control purposes. There are two modes of attachment: *direct* and *indirect*. Identities for use with the direct mode are encrypted using the jurisdiction\_keys item type (see **[dacskey(1)](/dacskey/1.md)**\[5\]); the program's user must therefore be able to read these keys. Changing these keys will invalidate all existing encrypted identities. Refer to the **imode**\[6\] flag for details.

The identity associated with an Rlink need not exist outside of its use by the Rlink.

The special, temporary credentials associated with an Rlink have the authentication style "rlink" (refer to **user()**\[7\] with the style keyword), but not passwd, even if a password is required to gain access to a resource.

For additional information, refer to the description of the **RLINK**\[8\] configuration directive and **[dacs\_acs(8)](/dacs_acs/8.md)**\[9\].

## OPTIONS

**dacsrlink** recognizes the standard *dacsoptions*\[1\], which are immediately followed by an operation name (*op*), various operation-dependent flags, and finally non-flag arguments. The **--** flag can be used to terminate the operation-dependent list of flags. Flags that are not recognized by the selected operation are ignored. A rule is always syntax checked (as by **[dacsacl(1)](/dacsacl/1.md)**\[4\]) before being written; if an error is found, the operation is aborted. Several flags are recognized by more than one operation.

By default, the virtual filestore item type rlinks specifies where Rlinks are stored. This can be overridden for most operations by giving the **-vfs** flag, which can specify a **DACS** URI, alternate item type, or absolute pathname.

**Security**\

Access to the rules and to listings of their names must be restricted, otherwise Rnames could be revealed. Only a **DACS** administrator should be permitted to list, create, modify, delete, etc. rules. **dacs\_acs** must be able to access the rules if Rlinks are enabled. Ensure that file permissions are set appropriately.

The optional **-out** flag is followed by a filename to which the rule should be written instead of a filestore. If "-" is given as the filename, the standard output is used.

The default alphabet used to generate Rnames can be overridden using the **-ralpha** flag; *alpha*, which follows the flag, is a character specification in the syntax of **strtr()**\[10\] (e.g., "a-zA-Z0-9", which is the default). The default length of an Rname can be overridden using the **-rlen** flag. Alternatively, some operations take a **-rname** flag that specifies the Rname to use.

The following *op* arguments are understood:

Perform a syntax check on the rule identified by *rname* to the standard output. If no error is found, an exit status of 0 is returned, otherwise an error message is produced and 1 is returned.

Create a new Rname that is virtually identical to that of *rname* (only the name differs). If the **-rname** flag is given, use *rname* as the Rname instead of generating one.

\[{**-a** \| **-allow**}*name*\] \[{**-p** *password*} \| {**-pf** *file*}\]...\
 \[**-palg** *alg-name*\] \[**-r** *redirect-URL*\] \[**-rname** *rname*\] \[**-ralpha** *alpha*\] \[**-rlen** *len*\]\
 \[**-expires** {*seconds* \| *date*}\] *path*...

Create a new, enabled Rlink and write it to either the filestore, a specified file, or the standard output. The optional **-a** (or **-allow**) flag is followed by *name*, which is a string that will become the argument to the **user()**\[11\] function that will be called from the allow clause of the ACL that is created. Each *name* will therefore be granted access to each of the named *path* arguments, which are URI path components relative to the current jurisdiction.

A password that applies only to this user can optionally follow as the next argument using a **-p** or **-pf** flag; its hashed value will be embedded in the Rlink and compared against a hash of an argument named *PASSWORD* that must be submitted with the Rlink. If a **-p** or **-pf** flag *precedes* any **-a** (**-allow**) flag, however, it establishes a default password for all users specified *later* on the command line. The **-pf** flag is followed by a filename from which the password is read; if *file* is "-", the password is read from the standard input. A password may be specified even if no **-a** flag is present; the request will not have an identity bound to it but a valid *PASSWORD* argument must be provided. The **-palg** flag overrides the default password hashing algorithm (see **password()**\[12\]).

If the **-rname** flag is given, *rname* is used as the Rname instead of generating one. The **-expires** flag assigns an expires\_expr attribute to the Rlink, which will render the Rlink invalid after the specified date. The flag is followed either by an unsigned integer, which is interpreted as a number of seconds in the future, or a date in one of the **recognized formats**\[13\].

If the **-r** flag appears, no usernames can be specified. An attempt to access any of the resources associated with the Rlink will cause the client to be redirected to *redirect-URL*, which may contain a properly encoded query component. This lets an Rlink serve as a "short link", akin to the services provided by **bitly.com**\[14\], **TinyURL.com**\[15\], and many others. Refer to the **redirect()**\[16\] function for additional information.

**Note**\
 Administrators should review the rule that is created. The **show**\[17\] operation can be used to display the rule and the **edit**\[18\] operation can be used to modify it.

Delete the Rname named *rname* in the selected filestore. This will effectively nullify all Rlinks that reference *rname*. To temporarily disable all Rlinks that reference an Rname, edit the rule and change its status attribute to disabled.

Interactively edit a copy of the rule named *rname* in the selected filestore. If the environment variable **EDITOR** is set, it is used as the name of the editor to use, otherwise the compile time symbol DEFAULT\_EDITOR is used. When editing is completed, the rule is replaced with the edited copy, provided the new version is syntactically correct.

Decode and print *rname-ident*, an Rname with an identity component produced by the **rlink** or **rname** operations.

Print a listing of all Rnames in the selected filestore.

Emit an Rlink to the standard output that integrates *rname* into the *uri* according to *link-mode*. The *link-mode* is one of dacs\_acs (or just acs), query, or path, representing the three general forms of an Rlink. If *ident* is specified, it describes a user in the **concise user syntax**\[19\] that is associated with the link. The *ident* may include an expiry date.

The **-imode** specifies whether a direct or indirect identity should be associated with the Rname, or whether there is none (the default). For direct, *ident* (specified by **-i** or **-ident**) is used; it describes an identity in the **concise user syntax**\[19\] that is associated with the link. For the indirect mode, a random identifier is generated (using the same algorithm selected for Rnames); if the **-iptr** flag is given, however, *iptr* is used as the identifier string.

If *uri* is a URI path component (i.e., it begins with a '/'), the configuration variable *rlink\_base\_prefix* must be defined; its value is prepended to the URI path.

Additional query arguments can be attached to the emitted link. If a password is required by the ACL for the resource, for example, a *PASSWORD* argument is required.

Implementation of query and path modes is incomplete, so URLs for those Rlinks must be generated manually.

\[**-rname** *rname*\]

This operation emits an Rname that satisfies the given constraints and prints it to the standard output. The Rname is suitable for use with the **-rname** flag. It does not create an ACL. This operation might be useful when Rlinks are created manually or using another program.

The **-imode**, **-i**, and **-iptr** flags are as described for the **rlink** operation.

Print the rule identified by *rname* to the standard output.

## EXAMPLES

The following examples assume that the jurisdiction EXAMPLE includes the following configuration:

```
RLINK '"${Args::RNAME:?}" /usr/local/dacs/rlinks'
EVAL   ${Conf::rlink_base_prefix} = "https://www.example.com"
VFS    "[rlinks]file:///usr/local/dacs/rlinks"
```

These directives enable Rlink processing by **[dacs\_acs(8)](/dacs_acs/8.md)**\[2\] and cause URLs generated by **dacsrlink** to be prefixed by https://www.example.com. ACLs that it creates will be stored as files in the /usr/local/dacs/rlinks directory.

This command creates an Rname called IRCl7p4Q, and associates it with the relative URL /cgi-bin/dacs/dacs\_prenv. The Rname will expire in 300 seconds (relative to this jurisdiction's clock):

```
% dacsrlink -uj EXAMPLE create -expires 300 /cgi-bin/dacs/dacs_prenv
IRCl7p4Q
```

Once an Rname has been created, a URL can be generated that incorporates the Rname:

```
% dacsrlink -uj EXAMPLE rlink -lmode acs IRCl7p4Q /cgi-bin/dacs/dacs_prenv
https://www.example.com/cgi-bin/dacs/dacs_prenv?DACS_ACS=-rname+IRCl7p4Q
```

In this example, the Rname has been incorporated into the URL through the **DACS\_ACS argument**\[20\].

To display the ACL for Rname IRCl7p4Q:

```
% dacsrlink -uj EXAMPLE show IRCl7p4Q
<acl_rule status="enabled" name="IRCl7p4Q" expires_expr='time(now) ge 1178917167'>
  <services>
    <service url_pattern="/cgi-bin/dacs/dacs_prenv"/>
  </services>
  <rule order="allow,deny">
   <allow>
   </allow>
  </rule>
</acl_rule>
```

Or, since the access control rule created by **dacsrlink** can be found in /usr/local/dacs/rlinks:

```
% cat /usr/local/dacs/rlinks/IRCl7p4Q
```

The default rule for **[dacs\_prenv(8)](/dacs_prenv/8.md)**\[21\] restricts access to a **DACS** administrator, but anyone who uses this Rlink before it expires will be granted access to **dacs\_prenv**. This rule can be manually customized at anytime. Note that unlike ordinary access control rules, there is no index file for Rlinks.

Suppose Rname 8D8m5CTj is this ACL:

```
<acl_rule status="enabled" name="8D8m5CTj">
  <services>
    <service url_pattern="/cgi-bin/dacs/special"/>
  </services>
  <rule order="allow,deny">
  <deny>
    if (${Args::EMAIL} == "bob@example.com") {
      redirect(BY_SIMPLE_REDIRECT, "http://dss.ca")
    }
    else {
      redirect(BY_SIMPLE_REDIRECT, "http://metalogicsoftware.ca")
    }
  </deny>
  </rule>
</acl_rule>
```

While it is not required to use **dacsrlink**, a command like the following might be used to conveniently construct a URL:

```
% dacsrlink -uj EXAMPLE rlink -lmode acs 8D8m5CTj '/cgi-bin/dacs/special?EMAIL=bob@example.com'
http://www.example.com/cgi-bin/dacs/special?DACS_ACS=-rname+8D8m5CTj&EMAIL=bob@example.com
```

In this example, a user who submits the link would be redirected to http://dss.ca. As usual, a resource corresponding to the path /cgi-bin/dacs/special does not need to actually exist at the jurisdiction. This ACL can be generalized to examine the request and other context and perform arbitrary actions, perhaps by using an external program - see **exec()**\[22\]. A **linkback**\[23\] can be implemented in this way, for instance.

This command creates a rule that applies to two resources and grants access to two users:

```
% dacsrlink -uj EXAMPLE create -a :auggie -a :harley /private/a.html /private/b.html
7tW3SJou
% dacsrlink -uj EXAMPLE show 7tW3SJou
<acl_rule status="enabled" name="7tW3SJou">
  <services>
      <service url_pattern="/private/a.html"/>
      <service url_pattern="/private/b.html"/>
  </services>
  <rule order="allow,deny">
   <allow>
       user(":auggie")
   </allow>
   <allow>
       user(":harley")
   </allow>
  </rule>
</acl_rule>
```

To generate URLs to give to these two users so that they can access these resource, commands like the following would be used:

```
% dacsrlink -uj EXAMPLE rlink -imode direct -i ":auggie" -lmode acs 7tW3SJou /private/a.html
https://www.example.com/private/a.html?DACS_ACS=-rname+7tW3SJou:HMGxWlccUihTtgbtJg
% dacsrlink -uj EXAMPLE rlink -imode direct -i ":harley" -lmode acs 7tW3SJou /private/b.html
https://www.example.com/private/b.html?DACS_ACS=-rname+7tW3SJou:qouYfT7pdwuLXHxodxE2
```

When the first of these links is invoked, it will appear as if EXAMPLE:auggie is accessing a.html. Since no expiration was specified for the identities or the resources, the two links will be valid indefinitely. The rule can be deleted at any time:

```
% dacsrlink -uj EXAMPLE delete 7tW3SJou
```

This demonstrates how to create a password-controlled link:

```
% dacsrlink -uj EXAMPLE create -a :auggie -p abracadabra /private/c.txt
rIPZaJeN
% dacsrlink -uj EXAMPLE show rIPZaJeN
<acl_rule status="enabled" name="rIPZaJeN">
  <services>
      <service url_pattern="/private/c.html"/>
  </services>
  <rule order="allow,deny">
   <allow>
       user(":auggie")
       and password(check, ${Args::PASSWORD}, "2|XYZZYnahdnl3VtLqGtpbW|2GoDncq34p2EMO4PA5Uj6iWkFb9")
   </allow>
  </rule>
</acl_rule>
% dacsrlink -uj EXAMPLE rlink -imode direct -i :auggie -lmode acs rIPZaJeN /private/c.txt
https://www.example.com/private/c.txt?DACS_ACS=-rname+rIPZaJeN:r6RdcTcmUyhTtgbtJg
% dacshttp "https://www.example.com/private/c.txt?DACS_ACS=-rname+rIPZaJeN:r6RdcTcmUyhTtgbtJg&PASSWORD=abracadabra"
Hello, world
```

## DIAGNOSTICS

The program exits 0 if everything was fine, 1 if an error occurred.

## SEE ALSO

**[dacs.acls(5)](/dacs.acls/5.md)**\[24\], **[dacs\_acs(8)](/dacs_acs/8.md)**\[2\]

## AUTHOR

Distributed Systems Software (**www.dss.ca**\[25\])

## COPYING

Copyright © 2003-2014 Distributed Systems Software. See the **LICENSE**\[26\] file that accompanies the distribution for licensing information.

## NOTES

- 1\.

  dacsoptions

  http://dacs.dss.ca/man/dacs.1.html#dacsoptions

- 2\.

  [dacs\_acs(8)](/dacs_acs/8.md)

  http://dacs.dss.ca/man/dacs\_acs.8.html

- 3\.

  acl.dtd

  http://dacs.dss.ca/man/../dtd-xsd/acl.dtd

- 4\.

  [dacsacl(1)](/dacsacl/1.md)

  http://dacs.dss.ca/man/dacsacl.1.html

- 5\.

  [dacskey(1)](/dacskey/1.md)

  http://dacs.dss.ca/man/dacskey.1.html

- 6\.

  imode

  http://dacs.dss.ca/man/#imode

- 7\.

  user()

  http://dacs.dss.ca/man/dacs.exprs.5.html#user.style

- 8\.

  RLINK

  http://dacs.dss.ca/man/dacs.conf.5.html#RLINK

- 9\.

  [dacs\_acs(8)](/dacs_acs/8.md)

  http://dacs.dss.ca/man/dacs\_acs.8.html#rlinks

- 10\.

  strtr()

  http://dacs.dss.ca/man/dacs.exprs.5.html#strtr

- 11\.

  user()

  http://dacs.dss.ca/man/dacs.exprs.5.html#user

- 12\.

  password()

  http://dacs.dss.ca/man/dacs.exprs.5.html#password

- 13\.

  recognized formats

  http://dacs.dss.ca/man/dacs.1.html#date\_formats

- 14\.

  bitly.com

  https://bitly.com

- 15\.

  TinyURL.com

  http://tinyurl.com

- 16\.

  redirect()

  http://dacs.dss.ca/man/dacs.exprs.5.html#redirect

- 17\.

  show

  http://dacs.dss.ca/man/#show\_op

- 18\.

  edit

  http://dacs.dss.ca/man/#edit\_op

- 19\.

  concise user syntax

  http://dacs.dss.ca/man/dacs.1.html#concise\_user\_syntax

- 20\.

  DACS\_ACS argument

  http://dacs.dss.ca/man/dacs\_acs.8.html#dacs\_acs\_argument

- 21\.

  [dacs\_prenv(8)](/dacs_prenv/8.md)

  http://dacs.dss.ca/man/dacs\_prenv.8.html

- 22\.

  exec()

  http://dacs.dss.ca/man/dacs.exprs.5.html#exec

- 23\.

  linkback

  http://en.wikipedia.org/wiki/Linkback

- 24\.

  [dacs.acls(5)](/dacs.acls/5.md)

  http://dacs.dss.ca/man/dacs.acls.5.html

- 25\.

  www.dss.ca

  http://www.dss.ca

- 26\.

  LICENSE

  http://dacs.dss.ca/man/../misc/LICENSE