#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass article
\language english
\inputencoding auto
\fontscheme times
\graphics default
\paperfontsize 12
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

High Level Design of User Revoke
\layout Author

Peter Braam, Eric Mei
\layout Date

Jan 31, 2005
\layout Section

Requirement
\layout Itemize

Be able to revoke a user, prevent it from accessing lustre immediately.
\layout Itemize

Be able to pass sub-test of HP acceptance 4.1.51.
\layout Itemize

user & mapping databases manipulation API.
\layout Section

Functional Specification
\layout Standard

A sub-command 
\begin_inset Quotes eld
\end_inset 

revoke
\begin_inset Quotes erd
\end_inset 

 will be added into existing tool 'lctl'.
 When system administrator want to kick somebody off from lustre filesystem
 (e.g.
 a certain user has known be malicious or an account be compromised), he
 could use this functionality on MDS's to prevent the victim user from access
 lustre filesystem right away.
 The command format could be:
\layout LyX-Code

lctl revoke user|all
\layout Itemize

Here the 'user' format is: uid[@nid[.netid]]
\layout Itemize

option @nid.netid is only for remote users.
 The uid is in term of local uid, thus 'uid@remote_nid.netid' means remote
 users on node 'remote_nid.netid' who are mapped to local 'uid', it's not
 intend to remove a certain user on specific node.
\layout Itemize

Specified uid without nid or netid means match all nid or netid.
\layout Itemize

'all' means revoke all users.
\layout Standard

Actually lctl only remove those in-kernel cache for the victim user, usually
 there's many other configuration work need to be done by using other admin
 tools:
\layout Itemize

Kerberos Database: For removing a user from kerberos principal database,
 sysadmin must use kerberos admin tools.
 And this change will not take effect right away if the victim user has
 authenticated with MDS's before the removal (because of client side credential
 cache).
\layout Itemize

User Database: For removing a user from user database, sysadmin also must
 resort to other tools, usually standard unix tools.
 This change will not take effect right away if this user had ever accessed
 lustre before the removal (because of in-kernel LSD cache).
\layout Itemize

User Mapping Database: For removing a user from remote user mapping database,
 sysadmin need edit the configure file manually.
 This only affect certain user on certain remote client.
 This change will not take effect right away if this user had ever acessed
 lustre before the removal (because of in-kernel uid mapping cache).
\layout Standard

So when sysadmin actually revoke a user, he usually at first did one or
 more steps of above according to requirement, then invoke lctl to finally
 revoke the user.
 In cases that user database or user mapping database are not centrally
 managed by e.g.
 LDAP, sysadmin must remove the user from all configure files on each MDS's,
 this could be done by using 'pdsh', etc.
\layout Standard

What above described is the basic requirement.
 There's an additional one: for user and mapping database, write a C API
 library (probably later add python support), which can query, add, remove,
 and enumerate users in each database.
 'edit' could be implemented as remove + add.
\layout Standard

By using this API, we could provide much complete functionality.
 Sysadmin could do everything about user account within single lctl tools;
 Kernel upcall helper also could use this API to obtain information from
 mapping database, etc.
\layout Section

Use Cases
\layout Subsection

Revoke Alice's access right on all clients, permanently
\layout Enumerate

Sysadmin remove Alice from user database on all MDS's.
\layout Enumerate

Sysadmin invoke 'lctl revoke alice_uid' on all MDS's.
\layout Enumerate

Alice from local clients will not be able to access lustre.
\layout Enumerate

Any remote users who are mapped to Alice will not be able to access lustre.
\layout Subsection

Revoke Alice's access right on remote client remote1
\layout Enumerate

Suppose alice@remote1 is mapped to local user Bob.
\layout Enumerate

Sysadmin remove mapping entry of 'alice_uid@remote1 -> bob' from user mapping
 database.
\layout Enumerate

Sysadmin invoke 'lctl revoke bob_uid@remote1' on all MDS's.
\layout Enumerate

Alice will not be able to access lustre from remote1.
\layout Enumerate

Bob from an local client could still work fine.
\layout Section

Logic Specification
\layout Standard

There's several kinds of in-kernel cache for certain user: LSD, gss context,
 and uid-mapping.
 In the future we might add consideration of removing OSS access capability.
\layout Enumerate

LSD: On each MDS, each user (uid) correspond to at most one LSD entry.
 There's already an existing interface to flush LSD for a certain user:
 simply write an uid into '/proc/fs/lustre/mds/lsd_flush' (Note this is
 subject to change).
 Write in '-1' will flush all LSD entries.
\layout Enumerate

GSS Context: On each MDS, each user (principal) might correspond to several(even
 many) gss contexts.
 The gss module should export a proc entry.
 When provided uid and remote nid/netid, it should be able to find out the
 initiating/established gss contexts and destroy them.
 Providing a special tag will flush all gss contexts.
\layout Enumerate

UID Mapping: Firstly found out per-client structure for specified nid/netid,
 then destroy the mapping entries for specified uid.
 Since this is strongly related to GSS context, we can use the export proc
 entry for gss context to initiate this flush.
 Thus when sysadmin trying to flush gss contexts for certain user, we also
 flush associated uid-mapping.
\layout Standard

This work should be done after the completion of GSS and remote uid/gid
 handling implementation.
\layout Standard

The user and mapping databases manipulation API could be simple not much
 restriction, and the details is very much related to the actual database
 structure.
 we leave the details to the following DLD document.
\layout Section

State Management
\layout Standard

Since we'll flush several cache separately, we might have situation that
 not strictly consistency.
 For example, after we flushed alice from cache1, someone re-populate it
 in cache1 while do it on cache2.
 In fact, the inconsistency between LSD and gss context is perfectly allowed.
 Only one thing need be sure is: since uid mapping is established after
 that of gss context, thus we need flush uid mapping at first, and then
 flush gss context.
 This could prevent unnecessary error when doing 'revoke' while we don't
 actually remote it from mapping database.
\layout Standard

No serious locking issues, no special recovery consideration.
\layout Section

Alternatives
\layout Standard

None.
\layout Section

Focus of Inspection
\layout Itemize

Is the lctl interface reasonably reflect the facts?
\layout Itemize

Could it pass acceptance test?
\the_end