Overview
Ranger 0.6 supports authorization of access based on tags associated with the resources, in addition to resource-based access authorization. Tag-based policy model offers many advantages over resource-based authorization model. One of the important advantages of this model is that it supports separation of resource-classification from access-authorization. This, in turn, allows security administrators to conceptualize and author access policies across multiple components (such as HDFS, Hive) in terms of type/class of data (which is a higher-level abstraction) as against in terms of component-specific resources as required by resource-based model.
Ranger tag policy model provides structures and abstractions to express and enforce tag-based policies. However, the tags (which embody a class of data contained by resources) are provisioned by an external system that maintains meta-data about the resources. This necessitates a tool to keep the external tag-source and Ranger Admin in synchronization.
Ranger suite includes a module, called Tag-Sync – short for Tag Synchronization Module - that enables synchronization of tagging information (such as entity-tag association as well value of tag-attributes if any) between a tag-source (usually, Atlas in the Apache-DGI ecosystem) and Ranger Admin.
Tag-sync module does not concern itself with how the entities are associated with tags and how the tag-attributes are initialized with values. It only ensures that any notifications regarding change to any entity-tag association and to tag-attribute values, are received and Ranger Admin is updated accordingly.
Tag-Sync module is implemented within Ranger as a stand-alone, daemon process named ranger-tagsync.
Installation
Tag-Sync is part of Apache-Ranger project distribution.
To install Tag-Sync:
- Log in to the installation machine as a super-user (root)
- Locate and download ranger-tagsync package and install it.
This will unpack and create a directory and needed sub-directories and files in “ranger-tagsync” directory under Apache installation root directory. This is ranger-tagsync-install-directory.
- Make ranger-tagsync-install-directory as your current working directory.
% cd ranger-tagsync-install-directory
- Set up the JAVA_HOME environment variable to point to Java distribution on the installation machine.
% export JAVA_HOME=location-of-java-home-on-the-machine
- Edit “install.properties” file in ranger-tagsync-install-directory to suit the operational environment.
Contents of this file are described in Configuration section in this document.
- Run setup script to create run-time directory structure.
% ./setup.sh
The run-time directory structure copies scripts into appropriate directories, creates files required for Atlas integration, creates configuration files which are used by ranger-tagsync process to configure itself, and sets up symbolic links wherever necessary.
Configuration
Tag-Sync configuration consists of providing property values for controlling following aspects of the module.
- Configuration of the source system (such as Atlas)
- Configuration of target of tags (Ranger Admin, also referred to as TagAdmin)
- Ranger-tagsync process control
The property values are provided by the Tag-Sync installer, in a simple file, named “install.properties”, in “name=value” format.
“install.properties” file contains the following properties.
PROPERTY | DESCRIPTION | COMMENTS |
TAGADMIN_ENDPOINT | URL of the destination of tags | Please customize the value to suit your deployment. |
TAGADMIN_SSL_CONFIG_FILENAME
| File containing SSL Configuration | Please customize the value to point to SSL configuration specific to your deployment. The value will be ignored in the scheme in TAGADMIN_ENPOINT URL is ‘http’. |
TAGSYNC_KEYSTORE_FILENAME
| File to store encrypted password for Ranger Admin user ‘rangertagsync’ that is used for communicating with TagAdmin | Please customize the value to suit your deployment. If there is no value specified then the password will not be encrypted. |
TAG_SOURCE
| Source of the tagging information | At this time, supported values are ‘atlas’, ‘atlasrest’, ‘file’ and ‘none’. |
TAGSYNC_ATLAS_KAFKA_ENDPOINTS
| URL of the Kafka endpoint to which Atlas sends its notifications. | Please customize the value to suit your deployment. |
TAGSYNC_ATLAS_ZOOKEEPER_ENDPOINT
| URL of the zookeeper endpoint needed for Atlas. | Please customize the value to suit your deployment. |
TAGSYNC_ATLAS_CONSUMER_GROUP
| String representing Kafka Consumer Group id used by Tag-Sync. | Please customize the value to suit your deployment. |
TAGSYNC_ATLAS_TO_RANGER_SERVICE_MAPPING
| Mapping between Atlas cluster-name, component-type and Ranger service-name | This mapping is provided as a string value in the following format. clusterName,componentType,serviceName;clusterName2,componentType2,serviceName;.., Please customize the value to suit your deployment. |
unix_user
| ranger-tagsync process is run as this Unix user. | There is no need to change this value (default is ‘ranger’). |
unix_group
| ranger-tagsync process is run with this Unix group-id. | There is no need to change this value (default is ‘ranger’). |
logdir | Directory where logs are store | Please customize the value to suit your deployment. |
TAG_SOURCE_ATLAS_REST_URL | URL of the Atlas Endpoint. If ‘atlasrest’ is one of the TAG_SOURCEs, then this needs to be set. | Please customize the value to suit your deployment. |
TAG_SOURCE_ATLAS_REST_DOWNLOAD_INTERVAL | Number of milliseconds between successive downloads of tags from Atlas when ‘atlasrest’ is one of the TAG_SOURCEs. | Please customize the value to suit your deployment. |
TAGSYNC_FILESOURCE_FILENAME
| File name containing tags if TAG_SOURCE is ‘file’ | Please customize the value to suit your deployment. A sample file is available at /etc/ranger/tagsync/conf/etc/ranger/data/tags.json |
TAG_SOURCE_FILE_MOD_TIME_CHECK_INTERVAL
| Interval for checking TAGSYNC_FILESOURCE_FILENAME for changes if TAG_SOURCE is ‘file’ | Please customize the value to suit your deployment. |
Updating password for Ranger Admin user ‘rangertagsync’
If, after installation, it is desired to change password of ‘rangertagsync’ user, then
- Change the password using Ranger Admin, AND,
- If password is stored in encrypted form, run updatetagadminpassword.sh script in ranger-tagsync-install-directory to update the password in the TAGSYNC_KEYSTORE_FILENAME keystore file; else update /etc/ranger/tagsync/conf/ranger-tagsync-site.xml file manually to update ‘ranger.tagsync.tagadmin.password’ property appropriately.
Run-time structure
A run-time directory structure is created after configuring property values in install.properties, and then executing setup.sh script.
Directory
| File | Linked to | Contains |
/etc/ranger/tagsync/conf |
| ranger-tagsync-install-directory/conf |
|
/etc/ranger/tagsync/conf | application.properties |
| Properties required for Atlas interface |
/etc/ranger/tagsync/conf | java_home.sh |
| Shell command to set JAVA_HOME environment variable |
/etc/ranger/tagsync/conf | log4j.xml |
| Log4j configuration properties |
/etc/ranger/tagsync/conf | ranger-tagsync-site.xml |
| Ranger-tagsync process configuration properties |
/etc/ranger/tagsync/conf | rangertagsync.jceks |
| Encrypted password for Ranger Admin user ‘rangertagsync’ |
/etc/init.d | ranger-tagsync |
| Shell script to start/stop/query ranger-tagsync service |
/usr/bin | ranger-tagsync-services.sh | ranger-tagsync-install-directory/ranger-tagsync.sh | Shell script to start/stop ranger-tagsync process |
/var/log/ranger/tagsync |
| ranger-tagsync-install-directory/log | Directory where logs (ranger-tagsync.log*) generated by ranger-tagsync are stored. |
/var/run/ranger | tagsync.pid |
| File containing process-id of the ranger-tagsync process, if it is running |
Usage
ranger-tagsync service may be started after Tag-Sync module is installed and configured.
To check if ranger-tagsync is running, log in as a super-user and execute
% service ranger-tagsync status
To start ranger-tagsync process, log in as a super-user and execute
% service ranger-tagsync start
To stop ranger-tagsync process, log in as a super-user and execute
% service ranger-tagsync stop
Ambari integration
At present, Tag-Sync module is not integrated with Ambari. It needs to be installed, configured and executed separately from rest of the modules in the Ranger suite using the command described in this document.
For integrating Tag-Sync with Ambari, a Ambari-interface file containing the properties in ranger-tagsync-site.xml and ranger-tagsync-default.xml (which is in the .jar file for ranger-tagsync) files (for configuring ranger-tagsync process) and properties in application.properties (for configuring Atlas interface) needs to set up.