L4Re/departure

Annotated docs/wiki/Users

457:ee511ba199af
23 months ago Paul Boddie file changeset files shortlog Improved the documentation in a number of areas.
paul@457 1 
= Users =
paul@457 2 
 
 paul@457      3 
Since filesystems such as ext2 employ the concepts of users and groups, and
 
 paul@457      4 
since access to such filesystems might be expected to respect the recorded
 
 paul@457      5 
user and group metadata, permitting or denying access to objects as
 
 paul@457      6 
appropriate, the need arises to define a user identity to control access to a
 
 paul@457      7 
filesystem server and the filesystem objects it exposes.
 
 paul@457      8 
 
 paul@457      9 
== Opener Configuration ==
 
 paul@457     10 
 
 paul@457     11 
Consequently, a filesystem server may not provide direct access to a
 
 paul@457     12 
filesystem. Instead, it may only expose the [[Components#Filesystems|
 
 paul@457     13 
`Filesystem`]] interface which provides the `open_for_user` operation. This
 
 paul@457     14 
operation is used to configure an [[Components#Openers|`Opener`]] that
 
 paul@457     15 
provides the actual interface for filesystem access as performed by a
 
 paul@457     16 
particular user.
 
 paul@457     17 
 
 paul@457     18 
Since the `open_for_user` operation involves the indication of an arbitrary
 
 paul@457     19 
user identity, a server providing the `Filesystem` interface should only be
 
 paul@457     20 
exposed to appropriately privileged components. An `Opener` obtained from the
 
 paul@457     21 
operation can then be presented to a less privileged component.
 
 paul@457     22 
 
 paul@457     23 
== User Structure ==
 
 paul@457     24 
 
 paul@457     25 
Ordinarily, user information is exchanged using a `user_t` structure defined
 
 paul@457     26 
in [[Libraries#libsystypes|`libsystypes`]] with the following members:
 
 paul@457     27 
 
 paul@457     28 
|| '''Member''' || '''Description'''       ||
 
 paul@457     29 
|| `uid`        || User identifier         ||
 
 paul@457     30 
|| `gid`        || Group identifier        ||
 
 paul@457     31 
|| `umask`      || File mode creation mask ||
 
 paul@457     32 
 
 paul@457     33 
The information broadly follows that of a traditional Unix system. Other
 
 paul@457     34 
information, such as supplementary groups might conceivably be provided to the
 
 paul@457     35 
filesystem server separately. Indeed, the user structure might be simplified,
 
 paul@457     36 
removing the primary group information and providing this separately, too.
 
 paul@457     37 
 
 paul@457     38 
== Opener Configuration in Ned ==
 
 paul@457     39 
 
 paul@457     40 
The following example illustrates the configuration of an opener and the
 
 paul@457     41 
provision of the opener to a new task in the Lua-based scripting environment
 
 paul@457     42 
of the Ned component in L4Re:
 
 paul@457     43 
 
 paul@457     44 
{{{
 
 paul@457     45 
-- Obtain user filesystems with umask 0022 (18).
 
 paul@457     46 
 
 paul@457     47 
local open_for_user = 6;
 
 paul@457     48 
local ext2svr_paulb = L4.cast(L4.Proto.Factory, ext2svr):create(open_for_user, 1000, 1000, 18);
 
 paul@457     49 
 
 paul@457     50 
l:startv({
 
 paul@457     51 
    caps = {
 
 paul@457     52 
      server = ext2svr_paulb,
 
 paul@457     53 
    },
 
 paul@457     54 
    log = { "client", "g" },
 
 paul@457     55 
  },
 
 paul@457     56 
  -- program, file to create
 
 paul@457     57 
  "rom/dstest_file_client", "home/paulb/new file");
 
 paul@457     58 
}}}
 
 paul@457     59 
 
 paul@457     60 
Here, `ext2svr_paulb` is an opener configured for the user `paulb` who has
 
 paul@457     61 
user and group identifiers of 1000. Since the Lua environment emphasises the
 
 paul@457     62 
L4Re factory mechanism, and since factory operations involve the use of L4Re
 
 paul@457     63 
variable-sized arguments ("vargs") as parameters, the signature of the factory
 
 paul@457     64 
version of the operation consists of the individual elements of the user
 
 paul@457     65 
abstraction:
 
 paul@457     66 
 
 paul@457     67 
{{{
 
 paul@457     68 
open_for_user(in ipc_varg_sys_uid_t uid,
 
 paul@457     69 
              in ipc_varg_sys_gid_t gid,
 
 paul@457     70 
              in ipc_varg_sys_mode_t umask,
 
 paul@457     71 
              out cap opener)
 
 paul@457     72 
}}}