knox-site/docs/webshell.md

Webshell

Introduction

This feature enables shell access to the machine running Apache Knox. Users can SSO into Knox and then access shell using the Knox WebShell URL on knox homepage. There are some out of band configuration changes that are required for the feature to work.

Prerequisite

This feature works only on *nix systems given it relies on sudoers file. Make sure following prerequisite are met before turning on the feature.

Make sure Knox process user (user under which knox process runs) exists on local machine.
Make sure the user used to login exists on local machine.
Make sure you have proper rights to create/update sudoers file descibed in “Configuration” section below.

Configuration

Webshell is not turned on by default. To enable Webshell following properties needs to be changed in gateway-site.xml

property>
    <name>gateway.websocket.feature.enabled</name>
    <value>true</value>
    <description>Enable/Disable websocket feature.</description>
</property>

<property>
    <name>gateway.webshell.feature.enabled</name>
    <value>true</value>
    <description>Enable/Disable webshell feature.</description>
</property>
<!-- in case JWT cookie validation for websockets is needed -->
<property>
    <name>gateway.websocket.JWT.validation.feature.enabled</name>
    <value>true</value>
    <description>Enable/Disable websocket JWT validation feature.</description>
</property>

Create a sudoers file /etc/sudoers.d/knox (assuming, Apache Knox process is running as user knox) with mappings for all the users that need WebShell acess on the machine running Apache Knox.

e.g. the following settings in sudoers file let's user sam and knoxui login to WebShell. Further restrictions on user sam and knoxui can be applied in sudoers file. More info: https://linux.die.net/man/5/sudoers. Here users sam and knoxui are SSO users that login using Knox authentication providers such as LDAP, PAM etc.

Defaults env_keep += JAVA_HOME
Defaults always_set_home
knox ALL=(sam:ALL) NOPASSWD: /bin/bash
knox ALL=(knoxui:ALL) NOPASSWD: /bin/bash