Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HBASE-12421 Clarify ACL concepts and best practices 

Signed-off-by: stack <stack@apache.org>
This commit is contained in:
Misty Stanley-Jones 2014-11-04 15:39:50 +10:00 committed by stack
parent 822bcce91e
commit 8e5503baa8
1 changed files with 387 additions and 386 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

773
src/main/docbkx/security.xml
View File

@ -573,233 +573,232 @@ grant 'rest_server', 'RWCA'
</note> </note>
<para>HBase has a simpler security model than relational databases, especially in terms of <para>HBase has a simpler security model than relational databases, especially in terms of
client operations. No distinction is made between an insert (new record) and update (of client operations. No distinction is made between an insert (new record) and update (of
existing record), for example, as both collapse down into a Put. Accordingly, the existing record), for example, as both collapse down into a Put.</para>
important operations condense to four permissions: READ, WRITE, CREATE, and ADMIN.</para> <section>
<table> <title>Understanding Access Levels</title>
<title>Operation To Permission Mapping</title> <para>HBase access levels are granted independently of each other and allow for different
<tgroup cols="2" align="left" colsep="1" rowsep="1"> types of operations at a given scope.</para>
<colspec colname="c1" align="center"/> <itemizedlist>
<colspec colname="c2" align="left"/>
<thead>
<row>
<entry>Permission</entry>
<entry>Operation</entry>
</row>
</thead>
<tbody>
<!-- READ -->
<row>
<entry>Read</entry>
<entry>Get</entry>
</row>
<row>
<entry/>
<entry>Exists</entry>
</row>
<row>
<entry/>
<entry>Scan</entry>
</row>
<!-- WRITE -->
<row>
<entry>Write</entry>
<entry>Put</entry>
</row>
<row>
<entry/>
<entry>Delete</entry>
</row>
<row>
<entry/>
<entry>IncrementColumnValue</entry>
</row>
<row>
<entry/>
<entry>CheckAndDelete/Put</entry>
</row>
<!-- CREATE -->
<row>
<entry>Create</entry>
<entry>Create</entry>
</row>
<row>
<entry/>
<entry>Alter</entry>
</row>
<row>
<entry/>
<entry>Drop</entry>
</row>
<row>
<entry/>
<entry>Bulk Load</entry>
</row>
<!-- ADMIN -->
<row>
<entry>Admin</entry>
<entry>Enable/Disable</entry>
</row>
<row>
<entry/>
<entry>Snapshot/Restore/Clone</entry>
</row>
<row>
<entry/>
<entry>Split</entry>
</row>
<row>
<entry/>
<entry>Flush</entry>
</row>
<row>
<entry/>
<entry>Compact</entry>
</row>
<row>
<entry/>
<entry>Major Compact</entry>
</row>
<row>
<entry />
<entry>Roll HLog</entry>
</row>
<row>
<entry/>
<entry>Grant</entry>
</row>
<row>
<entry/>
<entry>Revoke</entry>
</row>
<row>
<entry/>
<entry>Shutdown</entry>
</row>
<row>
<entry>Execute</entry>
<entry>Execute coprocessor endpoints</entry>
</row>
</tbody>
</tgroup>
</table>
<para> Permissions can be granted in any of the following scopes, though CREATE and ADMIN
permissions are effective only at table, namespace, and global scopes. </para>
<variablelist>
<varlistentry>
<term>Namespace</term>
<listitem> <listitem>
<para>Read (R) - can read data at the given scope</para>
</listitem>
<listitem>
<para><command>Write (W)</command> - can write data at the given scope</para>
</listitem>
<listitem>
<para><command>Execute (X)</command> - can execute coprocessor endpoints at the given
scope</para>
</listitem>
<listitem>
<para><command>Create (C)</command> - can create tables or drop tables (even those
they did not create) at the given scope</para>
</listitem>
<listitem>
<para><command>Admin (A)</command> - can perform cluster operations such as balancing
the cluster or assigning regions at the given scope</para>
</listitem>
</itemizedlist>
<para>The possible scopes are:</para>
<itemizedlist>
<listitem>
<para><command>Superuser</command> - superusers can perform any operation available in
HBase, to any resource. The user who runs HBase on your cluster is a superuser, as
are any principals assigned to the configuration property
<code>hbase.superuser</code> in <filename>hbase-site.xml</filename> on the
HMaster.</para>
</listitem>
<listitem>
<para><command>Global</command> - permissions granted at <filename>global</filename>
scope allow the admin to operate on all tables of the cluster.</para>
</listitem>
<listitem>
<para><command>Namespace</command> - permissions granted at
<filename>namespace</filename> scope apply to all tables within a given
namespace.</para>
</listitem>
<listitem>
<para><command>Table</command> - permissions granted at <filename>table</filename>
scope apply to data or metadata within a given table.</para>
</listitem>
<listitem>
<para><command>ColumnFamily</command> - permissions granted at
<filename>ColumnFamily</filename> scope apply to cells within that
ColumnFamily.</para>
</listitem>
<listitem>
<para><command>Cell</command> - permissions granted at <filename>cell</filename> scope
apply to that exact cell coordinate (key, value, timestamp). This allows for policy
evolution along with data.</para>
<para>To change an ACL on a specific cell, write an updated cell with new ACL to the
precise coordinates of the original.</para>
<para>If you have a multi-versioned schema and want to update ACLs on all visible
versions, you need to write new cells for all visible versions. The application
has complete control over policy evolution.</para>
<para>The exception to the above rule is <code>append</code> and
<code>increment</code> processing. Appends and increments can carry an ACL in the
operation. If one is included in the operation, then it will be applied to the
result of the <code>append</code> or <code>increment</code>. Otherwise, the ACL of
the existing cell you are appending to or incrementing is preserved.</para>
</listitem>
</itemizedlist>
<para>The combination of access levels and scopes creates a matrix of possible access
levels that can be granted to a user. In a production environment, it is useful to think
of access levels in terms of what is needed to do a specific job. The following list
describes appropriate access levels for some common types of HBase users. It is
important not to grant more access than is required for a given user to perform their
required tasks.</para>
<itemizedlist>
<listitem>
<para>Superusers - In a production system, only the HBase user should have superuser
access. In a development environment, an administrator may need superuser access in
order to quickly control and manage the cluster. However, this type of administrator
should usually be a Global Admin rather than a superuser.</para>
</listitem>
<listitem>
<para>Global Admins - A global admin can perform tasks and access every table in
HBase. In a typical production environment, an admin should not have Read or Write
permissions to data within tables.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Read: User can read any table in the namespace.</para> <para>A global admin with Admin permissions can perform cluster-wide operations on
the cluster, such as balancing, assigning or unassigning regions, or calling an
explicit major compaction. This is an operations role.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Write: User can write to any table in the namespace.</para> <para>A global admin with Create permissions can create or drop any table within
</listitem> HBase. This is more of a DBA-type role.</para>
<listitem>
<para>Create: User can create tables in the namespace.</para>
</listitem>
<listitem>
<para>Admin: User can alter table attributes; add, alter, or drop column families;
and enable, disable, or drop the table. User can also trigger region
(re)assignments or relocation.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>In a production environment, it is likely that different users will have only
one of Admin and Create permissions.</para>
<warning>
<para>In the current implementation, a Global Admin with <code>Admin</code>
permission can grant himself <code>Read</code> and <code>Write</code> permissions
on a table and gain access to that table's data. For this reason, only grant
<code>Global Admin</code> permissions to trusted user who actually need
them.</para>
<para>Also be aware that a <code>Global Admin</code> with <code>Create</code>
permission can perform a <code>Put</code> operation on the ACL table, simulating a
<code>grant</code> or <code>revoke</code> and circumventing the authorization
check for <code>Global Admin</code> permissions.</para>
<para>Due to these issues, be cautious with granting <code>Global Admin</code>
privileges.</para>
</warning>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term>Table</term>
<listitem> <listitem>
<itemizedlist> <para><command>Namespace Admins</command> - a namespace admin with <code>Create</code>
<listitem> permissions can create or drop tables within that namespace, and take and restore
<para>Read: User can read from any column family in table</para> snapshots. A namespace admin with <code>Admin</code> permissions can perform
</listitem> operations such as splits or major compactions on tables within that
<listitem> namespace.</para>
<para>Write: User can write to any column family in table</para>
</listitem>
<listitem>
<para>Create: User can alter table attributes; add, alter, or drop column
families; and drop the table.</para>
</listitem>
<listitem>
<para>Admin: User can alter table attributes; add, alter, or drop column families;
and enable, disable, or drop the table. User can also trigger region
(re)assignments or relocation.</para>
</listitem>
</itemizedlist>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term>Column Family / Column Qualifier / Cell</term>
<listitem> <listitem>
<itemizedlist> <para><command>Table Admins</command> - A table admin can perform administrative
<listitem> operations only on that table. A table admin with <code>Create</code> permissions
<para>Read: User can read at the specified scope.</para> can create snapshots from that table or restore that table from a snapshot. A table
</listitem> admin with <code>Admin</code> permissions can perform operations such as splits or
<listitem> major compactions on that table.</para>
<para>Write: User can write at the specified scope.</para>
</listitem>
</itemizedlist>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term>Coprocessor Endpoint</term>
<listitem> <listitem>
<para>Execute: the user can execute the coprocessor endpoint.</para> <para><command>Users</command> - Users can read or write data, or both. Users can also
execute coprocessor endpoints, if given <code>Executable</code> permissions.</para>
</listitem> </listitem>
</varlistentry> </itemizedlist>
<varlistentry> <table>
<term>Global</term> <title>Real-World Example of Access Levels</title>
<tgroup cols="4">
<thead>
<row>
<entry>Job Title</entry>
<entry>Scope</entry>
<entry>Permissions</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>Senior Administrator</para></entry>
<entry><para>Global</para></entry>
<entry><para>Access, Create</para></entry>
<entry><para>Manages the cluster and gives access to Junior
Administrators.</para></entry>
</row>
<row>
<entry><para>Junior Administrator</para></entry>
<entry><para>Global</para></entry>
<entry><para>Create</para></entry>
<entry><para>Creates tables and gives access to Table
Administrators.</para></entry>
</row>
<row>
<entry><para>Table Administrator</para></entry>
<entry><para>Table</para></entry>
<entry><para>Access</para></entry>
<entry><para>Maintains a table from an operations point of view.</para></entry>
</row>
<row>
<entry><para>Data Analyst</para></entry>
<entry><para>Table</para></entry>
<entry><para>Read</para></entry>
<entry><para>Creates reports from HBase data.</para></entry>
</row>
<row>
<entry><para>Web Application</para></entry>
<entry><para>Table</para></entry>
<entry><para>Read, Write</para></entry>
<entry><para>Puts data into HBase and uses HBase data to perform
operations.</para></entry>
</row>
</tbody>
</tgroup>
<caption><para>This table shows how real-world titles might map to HBase permissions in
a hypothetical company.</para></caption>
</table>
<formalpara>
<title>ACL Matrix</title>
<para>For more details on how ACLs map to specific HBase operations and tasks, see <xref
linkend="appendix_acl_matrix"/>.</para>
</formalpara>
</section>
<section>
<title>Implementation Details</title>
<para>Cell-level ACLs are implemented using tags (see <xref linkend="hbase.tags"/>). In
order to use cell-level ACLs, you must be using HFile v3 and HBase 0.98 or newer.</para>
<orderedlist>
<title>ACL Implementation Caveats</title>
<listitem> <listitem>
<para>Superusers are specified as a comma-separated list of users and groups, in the <para>Files created by HBase are owned by the operating system user running the HBase
<option>hbase.superuser</option> option in <filename>hbase-site.xml</filename>. process. To interact with HBase files, you should use the API or bulk load
The superuser is equivalent to the <literal>root</literal> user in a UNIX facility.</para>
environment. As a minimum, the superuser should include the principal used to run
the HMaster process. Global admin privileges, which are implicitly granted to the
superuser, are required to create namespaces, switch the balancer on and off, or
take other actions with global consequences. The superuser can also grant all
permissions to all resources.</para>
</listitem> </listitem>
</varlistentry> <listitem>
</variablelist> <para>HBase does not model "roles" internally in HBase. Instead, group names can be
<formalpara> granted permissions. This allows external modeling of roles via group membership.
<title>ACL Matrix</title> Groups are created and manipulated externally to HBase, via the Hadoop group mapping
<para>For more details on how ACLs map to specific HBase operations and tasks, see <xref service.</para>
linkend="appendix_acl_matrix"/>.</para> </listitem>
</formalpara> </orderedlist>
<para>Cell-level ACLs are implemented using tags (see <xref linkend="hbase.tags"/>). In </section>
order to use cell-level ACLs, you must be using HFile v3 and HBase 0.98 or newer.</para> <section>
<orderedlist> <title>Server-Side Configuration</title>
<title>ACL Implementation Caveats</title> <procedure>
<listitem> <step>
<para>Files created by HBase are owned by the operating system user running the HBase <para>As a prerequisite, perform the steps in <xref
process. To interact with HBase files, you should use the API or bulk load linkend="security.data.basic.server.side"/>.</para>
facility.</para> </step>
</listitem> <step>
<listitem> <para>Install and configure the AccessController coprocessor, by setting the following
<para>HBase does not model "roles" internally in HBase. Instead, group names can be properties in <filename>hbase-site.xml</filename>. These properties take a list of
granted permissions. This allows external modeling of roles via group membership. classes. </para>
Groups are created and manipulated externally to HBase, via the Hadoop group mapping <note>
service.</para> <para>If you use the AccessController along with the VisibilityController, the
</listitem> AccessController must come first in the list, because with both components active,
</orderedlist> the VisibilityController will delegate access control on its system tables to the
</section> AccessController. For an example of using both together, see <xref
<section> linkend="security.example.config"/>.</para>
<title>Server-Side Configuration</title> </note>
<procedure> <programlisting language="xml"><![CDATA[
<step>
<para>As a prerequisite, perform the steps in <xref
linkend="security.data.basic.server.side"/>.</para></step>
<step>
<para>Install and configure the AccessController coprocessor, by setting the following
properties in <filename>hbase-site.xml</filename>. These properties take a list of
classes. </para>
<note>
<para>If you use the AccessController along with the VisibilityController, the
AccessController must come first in the list, because with both components active,
the VisibilityController will delegate access control on its system tables to the
AccessController. For an example of using both together, see <xref
linkend="security.example.config"/>.</para></note>
<programlisting language="xml"><![CDATA[
<property> <property>
<name>hbase.coprocessor.region.classes</name> <name>hbase.coprocessor.region.classes</name>
<value>org.apache.hadoop.hbase.security.access.AccessController, org.apache.hadoop.hbase.security.token.TokenProvider</value> <value>org.apache.hadoop.hbase.security.access.AccessController, org.apache.hadoop.hbase.security.token.TokenProvider</value>
@ -817,15 +816,15 @@ grant 'rest_server', 'RWCA'
<value>true</value> <value>true</value>
</property> </property>
]]></programlisting> ]]></programlisting>
<para>Optionally, you can enable transport security, by setting <para>Optionally, you can enable transport security, by setting
<option>hbase.rpc.protection</option> to <literal>auth-conf</literal>. This requires <option>hbase.rpc.protection</option> to <literal>auth-conf</literal>. This
HBase 0.98.4 or newer.</para> requires HBase 0.98.4 or newer.</para>
</step> </step>
<step> <step>
<para>Set up the Hadoop group mapper in the Hadoop namenode's <para>Set up the Hadoop group mapper in the Hadoop namenode's
<filename>core-site.xml</filename>. This is a Hadoop file, not an HBase file. <filename>core-site.xml</filename>. This is a Hadoop file, not an HBase file.
Customize it to your site's needs. Following is an example.</para> Customize it to your site's needs. Following is an example.</para>
<programlisting language="xml"><![CDATA[ <programlisting language="xml"><![CDATA[
<property> <property>
<name>hadoop.security.group.mapping</name> <name>hadoop.security.group.mapping</name>
<value>org.apache.hadoop.security.LdapGroupsMapping</value> <value>org.apache.hadoop.security.LdapGroupsMapping</value>
@ -871,140 +870,140 @@ grant 'rest_server', 'RWCA'
<value>cn</value> <value>cn</value>
</property>]]> </property>]]>
</programlisting> </programlisting>
</step> </step>
<step> <step>
<para>Optionally, enable the early-out evaluation strategy. Prior to HBase 0.98.0, if a <para>Optionally, enable the early-out evaluation strategy. Prior to HBase 0.98.0, if
user was not granted access to a column family, or at least a column qualifier, an a user was not granted access to a column family, or at least a column qualifier, an
AccessDeniedException would be thrown. HBase 0.98.0 removed this exception in order to AccessDeniedException would be thrown. HBase 0.98.0 removed this exception in order
allow cell-level exceptional grants. To restore the old behavior in HBase to allow cell-level exceptional grants. To restore the old behavior in HBase
0.98.0-0.98.6, set <option>hbase.security.access.early_out</option> to 0.98.0-0.98.6, set <option>hbase.security.access.early_out</option> to
<literal>true</literal> in <filename>hbase-site.xml</filename>. In HBase 0.98.6, the <literal>true</literal> in <filename>hbase-site.xml</filename>. In HBase 0.98.6,
default has been returned to <literal>true</literal>.</para> the default has been returned to <literal>true</literal>.</para>
</step> </step>
<step> <step>
<para>Distribute your configuration and restart your cluster for changes to take <para>Distribute your configuration and restart your cluster for changes to take
effect.</para> effect.</para>
</step> </step>
<step> <step>
<para>To test your configuration, log into HBase Shell as a given user and use the <para>To test your configuration, log into HBase Shell as a given user and use the
<command>whoami</command> command to report the groups your user is part of. In this <command>whoami</command> command to report the groups your user is part of. In
example, the user is reported as being a member of the <code>services</code> this example, the user is reported as being a member of the <code>services</code>
group.</para> group.</para>
<screen> <screen>
hbase> <userinput>whoami</userinput> hbase> <userinput>whoami</userinput>
<computeroutput>service (auth:KERBEROS) <computeroutput>service (auth:KERBEROS)
groups: services</computeroutput> groups: services</computeroutput>
</screen> </screen>
</step> </step>
</procedure> </procedure>
</section> </section>
<section> <section>
<title>Administration</title> <title>Administration</title>
<para>Administration tasks can be performed from HBase Shell or via an API.</para> <para>Administration tasks can be performed from HBase Shell or via an API.</para>
<caution> <caution>
<title>API Examples</title> <title>API Examples</title>
<para>Many of the API examples below are taken from source files <para>Many of the API examples below are taken from source files
<filename>hbase-server/src/test/java/org/apache/hadoop/hbase/security/access/TestAccessController.java</filename> <filename>hbase-server/src/test/java/org/apache/hadoop/hbase/security/access/TestAccessController.java</filename>
and and
<filename>hbase-server/src/test/java/org/apache/hadoop/hbase/security/access/SecureTestUtil.java</filename>.</para> <filename>hbase-server/src/test/java/org/apache/hadoop/hbase/security/access/SecureTestUtil.java</filename>.</para>
<para>Neither the examples, nor the source files they are taken from, are part of the <para>Neither the examples, nor the source files they are taken from, are part of the
public HBase API, and are provided for illustration only. Refer to the public HBase API, and are provided for illustration only. Refer to the official API
official API for usage instructions.</para> for usage instructions.</para>
</caution> </caution>
<procedure> <procedure>
<step> <step>
<title>User and Group Administration</title> <title>User and Group Administration</title>
<para>Users and groups are maintained external to HBase, in your directory.</para> <para>Users and groups are maintained external to HBase, in your directory.</para>
</step> </step>
<step> <step>
<title>Granting Access To A Namespace, Table, Column Family, or Cell</title> <title>Granting Access To A Namespace, Table, Column Family, or Cell</title>
<para>There are a few different types of syntax for grant statements. The first, and <para>There are a few different types of syntax for grant statements. The first, and
most familiar, is as follows, with the table and column family being optional:</para> most familiar, is as follows, with the table and column family being
<screen>grant 'user', 'RWXCA', 'TABLE', 'CF', 'CQ'</screen> optional:</para>
<para>Groups and users are granted access in the same way, but groups are prefixed with <screen>grant 'user', 'RWXCA', 'TABLE', 'CF', 'CQ'</screen>
an <literal>@</literal> symbol. In the same way, tables and namespaces are specified <para>Groups and users are granted access in the same way, but groups are prefixed
in the same way, but namespaces are prefixed with an <literal>@</literal> with an <literal>@</literal> symbol. In the same way, tables and namespaces are
symbol.</para> specified in the same way, but namespaces are prefixed with an <literal>@</literal>
<para>It is also possible to grant multiple permissions against the same resource in a symbol.</para>
single statement, as in this example. The first sub-clause maps users to <para>It is also possible to grant multiple permissions against the same resource in a
ACLs and the second sub-clause specifies the resource.</para> single statement, as in this example. The first sub-clause maps users to ACLs and
<note> the second sub-clause specifies the resource.</para>
<para>HBase Shell support for granting and revoking access at the cell level is for <note>
testing and verification support, and should not be employed for production use <para>HBase Shell support for granting and revoking access at the cell level is for
because it won't apply the permissions to cells that don't exist yet. The correct testing and verification support, and should not be employed for production use
way to apply cell level permissions is to do so in the application code when storing because it won't apply the permissions to cells that don't exist yet. The correct
the values.</para> way to apply cell level permissions is to do so in the application code when
</note> storing the values.</para>
<formalpara> </note>
<title>ACL Granularity and Evaluation Order</title> <formalpara>
<para>ACLs are evaluated from least granular to most granular, and when an ACL is <title>ACL Granularity and Evaluation Order</title>
reached that grants permission, evaluation stops. This means that cell ACLs do not <para>ACLs are evaluated from least granular to most granular, and when an ACL is
override ACLs at less granularity.</para> reached that grants permission, evaluation stops. This means that cell ACLs do not
</formalpara> override ACLs at less granularity.</para>
<example> </formalpara>
<title>HBase Shell</title> <example>
<itemizedlist> <title>HBase Shell</title>
<listitem> <itemizedlist>
<para>Global:</para> <listitem>
<screen>hbase> <userinput>grant '@admins', 'RWXCA'</userinput></screen> <para>Global:</para>
</listitem> <screen>hbase> <userinput>grant '@admins', 'RWXCA'</userinput></screen>
<listitem> </listitem>
<para>Namespace:</para> <listitem>
<screen>hbase> <userinput>grant 'service', 'RWXCA', '@test-NS'</userinput></screen> <para>Namespace:</para>
</listitem> <screen>hbase> <userinput>grant 'service', 'RWXCA', '@test-NS'</userinput></screen>
<listitem> </listitem>
<para>Table:</para> <listitem>
<screen>hbase> <userinput>grant 'service', 'RWXCA', 'user'</userinput></screen> <para>Table:</para>
</listitem> <screen>hbase> <userinput>grant 'service', 'RWXCA', 'user'</userinput></screen>
<listitem> </listitem>
<para>Column Family:</para> <listitem>
<screen>hbase> <userinput>grant '@developers', 'RW', 'user', 'i'</userinput></screen> <para>Column Family:</para>
</listitem> <screen>hbase> <userinput>grant '@developers', 'RW', 'user', 'i'</userinput></screen>
<listitem> </listitem>
<para>Column Qualifier:</para> <listitem>
<screen>hbase> <userinput>grant 'service, 'RW', 'user', 'i', 'foo'</userinput></screen> <para>Column Qualifier:</para>
</listitem> <screen>hbase> <userinput>grant 'service, 'RW', 'user', 'i', 'foo'</userinput></screen>
<listitem> </listitem>
<para>Cell:</para> <listitem>
<para>The syntax for granting cell ACLs uses the following syntax:</para> <para>Cell:</para>
<screen>grant <replaceable>&lt;table&gt;</replaceable>, \ <para>The syntax for granting cell ACLs uses the following syntax:</para>
<screen>grant <replaceable>&lt;table&gt;</replaceable>, \
{ '<replaceable>&lt;user-or-group&gt;</replaceable>' => \ { '<replaceable>&lt;user-or-group&gt;</replaceable>' => \
'<replaceable>&lt;permissions&gt;</replaceable>', ... }, \ '<replaceable>&lt;permissions&gt;</replaceable>', ... }, \
{ <replaceable>&lt;scanner-specification&gt;</replaceable> }</screen> { <replaceable>&lt;scanner-specification&gt;</replaceable> }</screen>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><replaceable>&lt;user-or-group&gt;</replaceable> is the user or group <para><replaceable>&lt;user-or-group&gt;</replaceable> is the user or group
name, prefixed with <literal>@</literal> in the case of a group.</para> name, prefixed with <literal>@</literal> in the case of a group.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><replaceable>&lt;permissions&gt;</replaceable> is a string containing <para><replaceable>&lt;permissions&gt;</replaceable> is a string containing
any or all of "RWXCA", though only R and W are meaningful at cell any or all of "RWXCA", though only R and W are meaningful at cell
scope.</para> scope.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><replaceable>&lt;scanner-specification&gt;</replaceable> is the scanner <para><replaceable>&lt;scanner-specification&gt;</replaceable> is the
specification syntax and conventions used by the 'scan' shell command. For scanner specification syntax and conventions used by the 'scan' shell
some examples of scanner specifications, issue the following HBase Shell command. For some examples of scanner specifications, issue the following
command.</para> HBase Shell command.</para>
<screen>hbase> help "scan"</screen> <screen>hbase> help "scan"</screen>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>This example grants read access to the 'testuser' user and read/write access <para>This example grants read access to the 'testuser' user and read/write
to the 'developers' group, on cells in the 'pii' column which match the access to the 'developers' group, on cells in the 'pii' column which match the
filter.</para> filter.</para>
<screen>hbase> grant 'user', \ <screen>hbase> grant 'user', \
{ '@developers' => 'RW', 'testuser' => 'R' }, \ { '@developers' => 'RW', 'testuser' => 'R' }, \
{ COLUMNS => 'pii', FILTER => "(PrefixFilter ('test'))" }</screen> { COLUMNS => 'pii', FILTER => "(PrefixFilter ('test'))" }</screen>
<para>The shell will run a scanner with the given criteria, rewrite the found <para>The shell will run a scanner with the given criteria, rewrite the found
cells with new ACLs, and store them back to their exact coordinates.</para> cells with new ACLs, and store them back to their exact coordinates.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</example> </example>
<example> <example>
<title>API</title> <title>API</title>
<para>The following example shows how to grant access at the <para>The following example shows how to grant access at the table level.</para>
table level.</para> <programlisting language="java"><![CDATA[
<programlisting language="java"><![CDATA[
public static void grantOnTable(final HBaseTestingUtility util, final String user, public static void grantOnTable(final HBaseTestingUtility util, final String user,
final TableName table, final byte[] family, final byte[] qualifier, final TableName table, final byte[] family, final byte[] qualifier,
final Permission.Action... actions) throws Exception { final Permission.Action... actions) throws Exception {
@ -1025,37 +1024,38 @@ public static void grantOnTable(final HBaseTestingUtility util, final String use
}); });
} ]]> } ]]>
</programlisting> </programlisting>
<para>To grant permissions at the cell level, you can use the <para>To grant permissions at the cell level, you can use the
<code>Mutation.setACL</code> method:</para> <code>Mutation.setACL</code> method:</para>
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
Mutation.setACL(String user, Permission perms) Mutation.setACL(String user, Permission perms)
Mutation.setACL(Map<String, Permission> perms) Mutation.setACL(Map<String, Permission> perms)
]]> ]]>
</programlisting> </programlisting>
<para>Specifically, this example provides read permission to a user called <para>Specifically, this example provides read permission to a user called
<literal>user1</literal> on any cells contained in a particular Put <literal>user1</literal> on any cells contained in a particular Put
operation:</para> operation:</para>
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
put.setACL(“user1”, new Permission(Permission.Action.READ)) put.setACL(“user1”, new Permission(Permission.Action.READ))
]]></programlisting> ]]></programlisting>
</example> </example>
</step> </step>
<step> <step>
<title>Revoking Access Control From a Namespace, Table, Column Family, or Cell</title> <title>Revoking Access Control From a Namespace, Table, Column Family, or Cell</title>
<para>The <command>revoke</command> command and API are twins of the grant command and <para>The <command>revoke</command> command and API are twins of the grant command and
API, and the syntax is exactly the same. The only exception is that you cannot revoke API, and the syntax is exactly the same. The only exception is that you cannot
permissions at the cell level. You can only revoke access that has previously been revoke permissions at the cell level. You can only revoke access that has previously
granted, and a <command>revoke</command> statement is not the same thing as explicit been granted, and a <command>revoke</command> statement is not the same thing as
denial to a resource.</para> explicit denial to a resource.</para>
<note> <note>
<para>HBase Shell support for granting and revoking access is for testing and verification <para>HBase Shell support for granting and revoking access is for testing and
support, and should not be employed for production use because it won't apply the verification support, and should not be employed for production use because it
permissions to cells that don't exist yet. The correct way to apply cell-level won't apply the permissions to cells that don't exist yet. The correct way to
permissions is to do so in the application code when storing the values.</para> apply cell-level permissions is to do so in the application code when storing the
</note> values.</para>
<example> </note>
<title>Revoking Access To a Table</title> <example>
<programlisting language="java"> <title>Revoking Access To a Table</title>
<programlisting language="java">
<![CDATA[public static void revokeFromTable(final HBaseTestingUtility util, final String user, <![CDATA[public static void revokeFromTable(final HBaseTestingUtility util, final String user,
final TableName table, final byte[] family, final byte[] qualifier, final TableName table, final byte[] family, final byte[] qualifier,
final Permission.Action... actions) throws Exception { final Permission.Action... actions) throws Exception {
@ -1076,19 +1076,19 @@ put.setACL(“user1”, new Permission(Permission.Action.READ))
}); });
} ]]> } ]]>
</programlisting> </programlisting>
</example> </example>
</step> </step>
<step> <step>
<title>Showing a User's Effective Permissions</title> <title>Showing a User's Effective Permissions</title>
<example> <example>
<title>HBase Shell</title> <title>HBase Shell</title>
<screen>hbase> user_permission 'user'</screen> <screen>hbase> user_permission 'user'</screen>
<screen>hbase> user_permission '.*'</screen> <screen>hbase> user_permission '.*'</screen>
<screen>hbase> user_permission <replaceable>JAVA_REGEX</replaceable></screen> <screen>hbase> user_permission <replaceable>JAVA_REGEX</replaceable></screen>
</example> </example>
<example> <example>
<title>API</title> <title>API</title>
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
public static void verifyAllowed(User user, AccessTestAction action, int count) throws Exception { public static void verifyAllowed(User user, AccessTestAction action, int count) throws Exception {
try { try {
Object obj = user.runAs(action); Object obj = user.runAs(action);
@ -1104,9 +1104,10 @@ public static void verifyAllowed(User user, AccessTestAction action, int count)
} }
}]]> }]]>
</programlisting> </programlisting>
</example> </example>
</step> </step>
</procedure> </procedure>
</section>
</section> </section>
</section> </section>