ramackri commented on PR #1105:
URL: https://github.com/apache/ranger/pull/1105#issuecomment-5057842997
# Removing the `unixauthservice` Module from Apache Ranger
This document describes how to **remove** the entire Unix remote
authentication stack from Apache Ranger (target branch: `master`):
- **`unixauthservice`** — UserSync TCP listener
- **`unixauthclient`** — Ranger Admin JAAS client
- **`unixauthnative`** / **`unixauthpam`** — native validators
UserGroupSync (LDAP, file, Unix passwd/group sources) continues under a new
`ugsync` launcher. **No disable toggles** — delete the code and config.
## What `unixauthservice` Does Today
The module provides:
1. **`UnixAuthenticationService`** — a TCP/TLS listener (default port 5151)
that validates OS credentials via a native validator (`credValidator.uexe` /
`pamCredValidator.uexe`).
2. **`PasswordValidator` / `LoginAttemptTracker`** — rate limiting and
(optionally) account throttling for that listener.
3. **Usersync packaging assets** — install scripts, default config
(`ranger-ugsync-default.xml`), and service startup wiring bundled into the
**usersync tarball**.
UserGroupSync itself lives in **`ugsync/`** (`UserGroupSync`, LDAP/file
builders, etc.). The usersync process historically starts in the same JVM as
`UnixAuthenticationService` when `-enableUnixAuth` is passed on the command
line.
## Admin login vs `unixauthservice` (read this first)
People often conflate **PAM login for Ranger Admin**, **remote Unix login**,
and **UserGroupSync**. They are separate.
| Concern | Where it runs | Uses `unixauthservice` TCP (port 5151)? |
|---------|---------------|------------------------------------------|
| **UserGroupSync** (LDAP, file, `/etc/passwd` as a *source*) | UserSync JVM
| **No** — REST sync to Admin only |
| **Admin local PAM** (`PamLoginModule`) | Ranger Admin JVM on the **Admin
host** | **No** |
| **Remote Unix login** (`RemoteUnixLoginModule`) | Admin → UserSync host
listener | **Yes** — **removed by this change** |
### Admin local PAM (`PamLoginModule`) — **not** removed
For many on-prem Cloudera customers, Admin login uses **local PAM on the
Ranger Admin node** (inside the Admin JVM):
- Uses **libpam4j** (`org.jvnet.libpam.PAM`) → `pam.authenticate()` against
`/etc/pam.d` on the **Admin host**
- Config: **`ranger.pam.service`** (PAM service name)
- Does **not** connect to usersync port 5151
- Does **not** run `credValidator.uexe` / `pamCredValidator.uexe`
- Does **not** read `ranger.usersync.passwordvalidator.path`
After removal, `PamLoginModule` (and related JAAS classes) live under
**`security-admin/`**, not in deleted `unixauthclient/`.
`authentication_method=UNIX` and `authentication_method=PAM` both use this
local path after removal (`getPamAuthentication()`).
### Remote Unix login (`RemoteUnixLoginModule`) — **removed**
When `authentication_method=UNIX` and
**`ranger.pam.authentication.enabled=false`** (historical default for `UNIX`),
Admin used the **TCP client**:
1. `RemoteUnixLoginModule` (in `unixauthclient`) opens TLS to
`authServiceHostName:5151`
2. Sends `LOGIN: user password` to `UnixAuthenticationService` on the
**usersync host**
3. `PasswordValidator` spawns the native binary from
**`ranger.usersync.passwordvalidator.path`**
That validator runs on the **usersync node**, not on Admin:
| Binary (typical path) | What it does |
|----------------------|--------------|
| `credValidator.uexe` (default) | `/etc/shadow` + `crypt()` — OS password
check, **not PAM** |
| `pamCredValidator.uexe` (if configured) | PAM via `/etc/pam.d/...` on the
**usersync host** |
So `ranger.usersync.passwordvalidator.path` controls the **remote listener
only**. It is **not** used by Admin `PamLoginModule`. Removing
`unixauthservice` removes this remote path and those native validators —
**not** local PAM on Admin.
### What we delete vs what we keep
| Delete | Keep |
|--------|------|
| `unixauthservice` TCP listener | UserGroupSync |
| `RemoteUnixLoginModule` + `getUnixAuthentication()` | `PamLoginModule`
(moved to `security-admin`) |
| `credValidator.uexe` / `pamCredValidator.uexe` on usersync | Admin LDAP /
Kerberos / local PAM / JDBC |
| `ranger.unixauth.*` (Admin client to listener) | `ranger.pam.service`
(local PAM on Admin) |
### Critical: `UnixAuthenticationService` is also the process launcher
Today `UnixAuthenticationService.main()` does more than start the TCP auth
listener. It is the **usersync JVM entry point** that:
1. Initializes **`UserSyncHAInitializerImpl`** (Curator leader latch for HA
UserSync).
2. Starts **`UserGroupSync`** in a non-daemon background thread.
3. Optionally starts **`UserSyncMetricsProducer`** when
`ranger.usersync.metrics.enabled=true`.
4. Optionally starts the TCP auth listener when `-enableUnixAuth` is on the
command line (**removed entirely** — no config toggle replaces it).
Removing the module without replacing the non-auth launcher logic **breaks
HA UserSync and JVM metrics**, even if user/group sync itself still compiles.
Plan a new entry point in **`ugsync/`** (see [Changes in
`ugsync/`](#changes-in-ugsync)).
## Removal Scope — one change, full stack
Remove **all** Unix remote authentication code from Ranger in a single
effort. There is no “server-only” partial removal that leaves Admin client code
behind.
### Modules to delete
| Module | Path | What it does |
|--------|------|--------------|
| `unixauthservice` | `unixauthservice/` | TCP listener on port 5151;
**remote** OS password check for Admin login (via native validator on usersync
host) |
| `unixauthclient` | `unixauthclient/` | JAAS client in **Ranger Admin** —
connects Admin UI login to that listener |
| `unixauthnative` | `unixauthnative/` | Builds `credValidator.uexe` (native
password check for listener) |
| `unixauthpam` | `unixauthpam/` | Builds `pamCredValidator.uexe` (PAM
validator for listener) |
### What `unixauthclient` is (and why it goes too)
Remote Unix login was a **two-part** feature:
```mermaid
flowchart LR
subgraph admin [Ranger Admin — remove client]
A[RangerAuthenticationProvider.getUnixAuthentication]
B[RemoteUnixLoginModule / unixauthclient]
end
subgraph usersync [UserSync JVM — remove listener]
C[UnixAuthenticationService :5151]
D[UserGroupSync]
end
A --> B
B -->|TCP| C
D -->|REST sync| admin
```
| Part | Location | Action |
|------|----------|--------|
| **Listener (server)** | `unixauthservice` on UserSync host | **Delete
module** |
| **Client** | `unixauthclient` in Admin WAR | **Delete module** — useless
without listener |
| **Native validators** | `unixauthnative`, `unixauthpam` | **Delete
modules** — only used by listener |
**Do not** remove the listener but keep `unixauthclient` or
`ranger.unixauth.*` config — that is dead code, not removal.
**Do not** add `ranger.usersync.unix.auth.enabled` or any disable toggle —
delete the feature.
### What stays (unchanged)
| Component | Module |
|-----------|--------|
| LDAP / file / Unix **user-group sync** | `ugsync/` — `UserGroupSync`,
builders, REST to Admin |
| HA UserSync | `UserSyncHAInitializerImpl` — move init into new `ugsync`
launcher |
| JVM metrics | `UserSyncMetricsProducer` — move start into new launcher |
| Admin LDAP / Kerberos / **local PAM** / local DB | `security-admin/` —
`PamLoginModule` relocated here; unrelated to deleted TCP client |
### Not in scope (do not implement)
| Approach | Why skip |
|----------|----------|
| CDPD-80522 “disable by default” | Keeps modules alive with a config flag —
**removal, not disabling** |
| [CDH/ranger PR
#751](https://github.infra.cloudera.com/CDH/ranger/pull/751) | Same — opt-in
while code remains |
---
## Changes in `ugsync/`
Required for removal — not optional cleanup.
### 1. `UserGroupSyncConfig.java`
**File:**
`ugsync/src/main/java/org/apache/ranger/unixusersync/config/UserGroupSyncConfig.java`
| Change | Detail |
|--------|--------|
| **Do not add** `ranger.usersync.unix.auth.enabled` | That is a
disable/opt-in pattern; removal deletes the listener entirely |
| **Remove** auth-listener property constants/accessors if any exist | Port,
SSL, password validator path were read by `UnixAuthenticationService`, not by
core sync |
| **Keep** all sync-related config | LDAP, file, unix min uid/gid, policy
manager URL, HA, metrics, deletes, validation, etc. |
**Not UnixAuth-specific (unchanged):** `ranger.usersync.enabled`,
source/sink impl classes, LDAP props, sleep intervals, SSL keystore props used
for **LDAP** TLS to Admin (if applicable), etc.
**Tests:** `TestUserGroupSyncConfig.java` — no new toggle tests; verify sync
config still loads after relocated `ranger-ugsync-default.xml`.
### 2. New usersync JVM entry point (required)
**Do not** point startup scripts at bare `UserGroupSync.main()` alone — it
does not initialize HA or metrics.
Add a launcher in `ugsync/` (e.g. `UserSyncService`) that replicates the
**non-auth** portion of `UnixAuthenticationService`:
| Responsibility | Source today (`UnixAuthenticationService`) | New launcher
|
|----------------|---------------------------------------------|--------------|
| HA init | `UserSyncHAInitializerImpl.getInstance(...)` | Same |
| Start sync thread | `startUnixUserGroupSyncProcess()` → `UserGroupSync` |
Same |
| Start metrics thread | `UserSyncMetricsProducer` when enabled | Same |
| Block main thread | Auth `accept()` loop today | **Join/wait** on sync (or
infinite wait) — must not exit and tear down HA in `finally` |
| TCP auth listener | `init()` + `startService()` | **Delete** — do not
relocate |
**Tests to add/move:** HA + metrics startup tests from
`unixauthservice/src/test/.../TestUnixAuthenticationService.java` → `ugsync`
tests.
### 3. Other `ugsync/` file edits
| File | Change |
|------|--------|
| `UserGroupSync.java` | Optional: fold launcher into `main()` or separate
`UserSyncService.java` |
| `FileSourceUserGroupBuilder.java` | Error message:
`unixauthservice.properties` → `ranger-ugsync-site.xml` |
| `ranger-ugsync-site.xml` (test resources) | Remove `unixauthservice.jks` /
auth-only paths |
| `UserSyncHAInitializerImpl.java` | No API change; launcher must call
`getInstance()` before sync |
| `UserSyncMetricsProducer.java` | No change; launcher starts it |
### 4. Usersync config XML — **delete** auth properties
**File:** `ranger-ugsync-default.xml` (relocated from
`unixauthservice/conf.dist/`)
**Remove** (auth listener only — no replacement toggle):
| Property | Reason |
|----------|--------|
| `ranger.usersync.port` | TCP listener port 5151 |
| `ranger.usersync.ssl` | Listener TLS |
| `ranger.usersync.passwordvalidator.path` | Native validator for listener |
| `ranger.usersync.unixauth.*` | Rate limits (RANGER-5690) — listener
deleted |
| `ranger.usersync.unix.auth.enabled` | **Do not add** — not part of removal
|
**Keep:**
| Property | Reason |
|----------|--------|
| `ranger.usersync.enabled` | Core sync on/off |
| LDAP / file / unix source props | Sync sources |
| `ranger.usersync.metrics.enabled` | JVM metrics |
| `ranger-ugsync.server.ha.enabled` | HA |
| Policy manager URL, sleep intervals, etc. | Core sync |
Also update: `scripts/templates/ranger-ugsync-template.xml`,
`installprop2xml.properties` — **remove** `AUTH_*` mappings (`AUTH_SSL_*`,
port, validator); `install.properties` — remove `AUTH_*` keys and
`unixauthservice.jks` defaults.
---
## Step 1 — Relocate Assets (Do Not Delete Blindly)
Several paths under `unixauthservice/` are **not** auth-server-only; they
are consumed by the **usersync distribution**. Move them before deleting the
module (suggested target: `ugsync/` or a new `usersync-packaging/` directory).
### Relocate from `unixauthservice/conf.dist/`
| File | Purpose |
|------|---------|
| `ranger-ugsync-default.xml` | Default usersync config — **strip auth
listener properties** after relocate |
| `logback.xml` | Usersync logging defaults |
| `jaas.conf` | Was under `conf.dist/` — **delete** if only used by removed
unixauth stack; verify no other consumer |
### Relocate from `unixauthservice/scripts/`
| File / directory | Purpose |
|------------------|---------|
| `start.sh`, `stop.sh` | Usersync service control |
| `setup.sh`, `setup.py` | Usersync install |
| `install.properties` | Install-time properties template |
| `ranger-usersync-services.sh` | Change main class to new `ugsync`
launcher; **remove** `-enableUnixAuth` and `UnixAuthenticationService` |
| `initd` | Init script source for assembly |
| `templates/` | Config templates |
| `updatepolicymgrpassword.sh`, `updatepolicymgrpassword.py`,
`update_property.py`, `set_globals.sh` | Install/upgrade helpers |
### Optional / generated
| Path | Notes |
|------|-------|
| `unixauthservice/cert/` | Referenced by
`distro/src/main/assembly/usersync.xml`; may be empty in source (certs
generated at install) |
After relocation, update **`distro/src/main/assembly/usersync.xml`** so all
`../unixauthservice/...` paths point to the new location.
---
## Step 2 — Delete Module Directories
Remove entire directories after assets are relocated:
```
unixauthservice/ # listener + usersync packaging (relocate non-auth
assets first)
unixauthclient/ # Admin JAAS client
unixauthnative/ # credValidator native build
unixauthpam/ # pamCredValidator native build
```
`unixauthservice/` contents before delete:
├── pom.xml
├── conf.dist/ (after relocation)
├── scripts/ (after relocation)
├── src/main/java/org/apache/ranger/authentication/
│ ├── UnixAuthenticationService.java
│ ├── PasswordValidator.java
│ └── LoginAttemptTracker.java
├── src/test/java/org/apache/ranger/authentication/
│ ├── TestUnixAuthenticationService.java
│ ├── TestPasswordValidator.java
│ └── LoginAttemptTrackerTest.java
└── src/main/resources/logback.xml
```
---
## Step 3 — Edit Build and Packaging
### Root Maven reactor
**File:** `pom.xml`
Remove `<module>` entries for **all four**:
- `unixauthservice`
- `unixauthclient`
- `unixauthnative`
- `unixauthpam`
(typically three profile blocks each.)
### Distribution dependencies
**File:** `distro/pom.xml`
Remove dependencies on `unixauthservice` and `unixauthclient`.
### Admin assembly
**File:** `distro/src/main/assembly/admin-web.xml`
Remove `<include>org.apache.ranger:unixauthclient</include>`.
### Usersync assembly descriptor
**File:** `distro/src/main/assembly/usersync.xml`
1. Remove `<include>org.apache.ranger:unixauthservice</include>` from the
module set.
2. Repoint file sets that reference `../unixauthservice/conf.dist`,
`../unixauthservice/scripts`, `../unixauthservice/cert`, and `initd` to
relocated paths.
3. **Remove** native validator file sets (`../unixauthnative/target`,
`../unixauthpam/target`).
4. Keep `unixusersync` / `ugsync` module includes unchanged unless
restructuring modules.
---
## Step 4 — Edit Runtime and Install Scripts
Replace `UnixAuthenticationService` startup with the new `ugsync` launcher.
| File | Change |
|------|--------|
| `ranger-usersync-services.sh` (relocated) | `java ...
org.apache.ranger.usergroupsync.UserSyncService` (or chosen launcher); **no**
`-enableUnixAuth` |
| `dev-support/ranger-docker/scripts/usersync/ranger-usersync.sh` | PID via
PID file or `proc_rangerusersync` (see [Docker
CI](#docker-ci-ranger-usersyncsh-pid-detection)) |
|
`dev-support/ranger-docker/scripts/usersync/ranger-usersync-install.properties`
| Remove `AUTH_*` / `unixauthservice.jks` entries |
| `security-admin/src/bin/ranger_usersync.py` | `java_class` → new `ugsync`
launcher |
See also [Changes in `ugsync/`](#changes-in-ugsync) and [Ranger Admin and
`unixauthclient`](#ranger-admin-and-unixauthclient-removal).
---
## Ranger Admin and `unixauthclient` (removal)
Remove the **Admin-side client** in the same PR as the UserSync listener.
Keeping `unixauthclient` while deleting `unixauthservice` is not removal — it
leaves broken login code in the Admin WAR.
### Admin Java and config
| File | Change |
|------|--------|
| `security-admin/pom.xml` | Remove `unixauthclient` dependency |
| `security-admin/.../RangerAuthenticationProvider.java` | Remove
`getUnixAuthentication()` and `RemoteUnixLoginModule` wiring; **`UNIX` →
`getPamAuthentication()` only** |
| `security-admin/.../authentication/unix/jaas/PamLoginModule.java` |
**Keep** — relocated from `unixauthclient`; local PAM on Admin host |
| `security-admin/.../TestRangerAuthenticationProvider.java` | Remove
`getUnixAuthentication_*` tests |
|
`security-admin/src/main/resources/conf.dist/ranger-admin-default-site.xml` |
**Delete** all `ranger.unixauth.*` properties |
| `security-admin/scripts/setup.sh` | Rename `do_unixauth_setup()` →
`do_unix_authentication_method_setup()`; remove `ranger_unixauth_*` keystore
handling |
| `security-admin/scripts/install.properties` | Remove
`ranger_unixauth_keystore`, truststore, etc. |
|
`security-admin/src/main/java/org/apache/ranger/common/PropertiesUtil.java` |
Remove unixauth keystore/truststore credential helpers |
| `security-admin/scripts/upgrade_admin.py` | Remove `unixauth.properties` /
JAAS migration paths |
### Admin `ranger.unixauth.*` properties to delete
| Property | Was used for |
|----------|--------------|
| `ranger.unixauth.remote.login.enabled` | Enable Admin remote Unix login |
| `ranger.unixauth.service.hostname` | UserSync host running listener |
| `ranger.unixauth.service.port` | Listener port (5151) |
| `ranger.unixauth.ssl.enabled` | TLS to listener |
| `ranger.unixauth.keystore` / `.password` / `.credential.alias` | Admin
client keystore |
| `ranger.unixauth.truststore` / `.password` / `.credential.alias` | Admin
client truststore |
| `ranger.unixauth.server.cert.validation` | Cert validation |
| `ranger.unixauth.debug` | Debug logging |
### `unixauthclient/` module
Delete the module. It contained **`RemoteUnixLoginModule`** (TCP client to
the listener) — that is what we remove.
**Keep (relocated to `security-admin/`):** `PamLoginModule`, `PamPrincipal`,
callback handlers, and their tests — local PAM on the Admin host, **no**
unixauthservice dependency.
### Upgrade (clusters using remote Unix login today)
1. Enable LDAP/Kerberos/**local PAM on Admin** (`authentication_method=UNIX`
or `PAM`) **before** upgrading if you used **remote** Unix login
(`ranger.unixauth.*` / usersync listener).
2. After upgrade, remove stale `ranger.unixauth.*` from config management
(Ambari/Cloudera Manager).
3. There is **no** property to re-enable the feature — it is removed from
the codebase.
---
## Docker CI: `ranger-usersync.sh` PID detection
**File:** `dev-support/ranger-docker/scripts/usersync/ranger-usersync.sh`
Today the script keeps the Docker container alive with:
```bash
RANGER_USERSYNC_PID=`ps -ef | grep -v grep | grep -i
"org.apache.ranger.authentication.UnixAuthenticationService" | awk '{print $2}'`
tail --pid=$RANGER_USERSYNC_PID -f /dev/null
```
### Why this works on current master
The JVM main class in `ps` is always `UnixAuthenticationService`, even
though the same process also starts UserGroupSync:
```java
public void run() {
try {
LOG.info("Starting User Sync Service!");
startUnixUserGroupSyncProcess();
Thread.sleep(5000);
if (enableUnixAuth) {
LOG.info("Enabling Unix Auth Service!");
init();
startService();
} else {
LOG.info("Unix Auth Service Disabled!");
}
```
With `-enableUnixAuth`, the main thread blocks in the auth listener loop, so
the process stays up and the grep finds it. Docker CI uses this line only to
keep the container alive (`tail --pid=...`).
### What is wrong with it (conceptually)
| Issue | Detail |
|-------|--------|
| **Misleading** | Variable is `RANGER_USERSYNC_PID` but the grep matches
`UnixAuthenticationService`, not `UserGroupSync` |
| **Coupled to UnixAuth** | Usersync lifecycle is tied to a class you may
remove |
| **After removal** | If startup becomes `UserGroupSync` (or another main),
this grep returns empty → container exits → CI fails |
| **Fragile matching** | String grep on full command line; renames or
package moves break it |
| **Multiple PIDs** | If several lines match, `awk '{print $2}'` can yield
multiple PIDs and break `tail --pid=` |
### Better options (especially after removal)
**1. Use the PID file** (already written by `ranger-usersync-services.sh`):
```bash
pidf=${USERSYNC_PID_DIR_PATH:-/var/run/ranger}/${USERSYNC_PID_NAME:-usersync.pid}
RANGER_USERSYNC_PID=$(cat "$pidf" 2>/dev/null)
```
**2. Grep the usersync process marker** (already on the `java` command line):
```bash
RANGER_USERSYNC_PID=$(ps -ef | grep -v grep | grep 'proc_rangerusersync' |
awk '{print $2}')
```
**3. After `unixauthservice` removal**, grep the new main class if it
becomes the direct entry point, e.g.:
```bash
grep -i "org.apache.ranger.usergroupsync.UserGroupSync"
```
### Short answer
| Question | Answer |
|----------|--------|
| Correct for current master with `-enableUnixAuth`? | **Yes** — finds the
running usersync JVM |
| Correct name/intent for “usersync PID”? | **No** — it is really the
UnixAuth wrapper JVM |
| Still correct after removing `unixauthservice`? | **No** — must change
startup **and** this line |
If you drop the module entirely, update startup to the new `ugsync` launcher
**and** this PID line (PID file or `proc_rangerusersync` — do not grep
`UnixAuthenticationService`).
---
## Step 5 — Clean Up References (Optional but Recommended)
### `ugsync/` and tests
| File | Reference |
|------|-----------|
| `ugsync/.../FileSourceUserGroupBuilder.java` | Error message mentions
`unixauthservice.properties` |
| `ugsync/src/test/resources/ranger-ugsync-site.xml` | `unixauthservice.jks`
keystore path |
| `ugsync/src/test/java/.../TestUserGroupSyncConfig.java` | Verify sync
config after auth props removed from defaults |
### Packaging / install (relocated scripts)
| File | Reference |
|------|-----------|
| `setup.py` | Remove `unixauthservice.jks` cert generation — or delete auth
cert setup entirely |
| `updatepolicymgrpassword.sh` | Rename `unixauthservice.properties` →
usersync naming |
| `install.properties` | Remove `AUTH_*` keys and `unixauthservice.jks`
paths |
| `installprop2xml.properties` | Remove `AUTH_SSL_*` mappings |
### Docker / dev-support
| File | Reference |
|------|-----------|
|
`dev-support/ranger-docker/scripts/usersync/ranger-usersync-install.properties`
| `AUTH_SSL_KEYSTORE_FILE=.../unixauthservice.jks` |
| `dev-support/ranger-docker/Dockerfile.ranger-usersync` | Symlinks
`ranger-usersync-services.sh`; no change unless main class changes |
| `dev-support/ranger-docker/docker-compose.ranger-usersync.yml` | Mounts
install.properties |
### Migration utilities
| File | Reference |
|------|-----------|
|
`migration-util/ambari2.0-hdp2.2-ranger0.40/bin/import_ranger_to_ambari.py` |
`unixauthservice.properties` path |
|
`migration-util/ambari2.1-hdp2.3-ranger0.50/bin/import_ranger_to_ambari.py` |
Remove `ranger.usersync.port`, `.ssl`, `.passwordvalidator.path`,
`ranger.unixauth.*` mappings |
### Docs / security
| File | Reference |
|------|-----------|
| `THREAT_MODEL.md` | Lists `unixauthservice/` under Authentication |
| `mkdocs/docs/project/cve-list.md` | CVE entries for
`UnixAuthenticationService` |
| `mkdocs/docs/project/release-process.md` | May reference
`unixauthnative/pom.xml` |
| `security-admin/scripts/upgrade_admin.py` | Remove `unixauth.properties` /
JAAS migration paths |
| `unixauthclient/src/test/.../TestRemoteUnixLoginModule.java` | Delete with
module |
| `unixauthclient/src/test/.../UnixAuthenticationTester.java` | Delete with
module |
### Native validators
| Module | Action |
|--------|--------|
| `unixauthnative/` | **Delete** — `credValidator.uexe` only served deleted
listener |
| `unixauthpam/` | **Delete** — `pamCredValidator.uexe` same |
---
## Post-Removal Behavior
| Component | After removal |
|-----------|---------------|
| **UserGroupSync** | Continues via new `ugsync` launcher (LDAP, file, Unix
passwd/group sources) |
| **UserSync HA / metrics** | Works if new launcher initializes HA and
starts metrics |
| **Remote Unix Admin login** | **Removed** — `RemoteUnixLoginModule` and
listener deleted |
| **Admin `authentication_method=UNIX` or `PAM`** | **Still supported** —
local PAM on Admin via `PamLoginModule` in `security-admin` (libpam4j,
`ranger.pam.service`) |
| **Admin auth (other)** | LDAP, Kerberos, PAM, local DB (`NONE`) |
| **Docker CI usersync** | Still works (file-based sync); update PID
detection |
---
## Verification Checklist
```bash
# Reactor should not list unix auth modules
grep -E 'unixauth(service|client|native|pam)' pom.xml distro/pom.xml
# Full build
mvn -pl distro -am package -DskipTests
# Inspect tarballs
tar tzf distro/target/ranger-*-usersync.tar.gz | head
tar tzf distro/target/ranger-*-admin.tar.gz | grep -i unixauth || echo "OK:
no unixauth in admin tarball"
# Confirm no UnixAuthenticationService in startup scripts
grep -r UnixAuthenticationService dev-support/ security-admin/src/bin/
<relocated-scripts>/
# Confirm no unixauthclient in Admin
grep -r unixauthclient security-admin/ distro/
```
Expected:
- [x] `mvn` reactor builds without `unixauthservice`, `unixauthclient`,
`unixauthnative`, `unixauthpam`
- [x] Usersync tarball: relocated scripts/config; `dist/unixusersync-*.jar`
+ `lib/*`; **no** native validators; **no** auth listener props
- [x] Admin tarball: **no** `unixauthclient`; **no** `ranger.unixauth.*` in
defaults
- [x] `getUnixAuthentication()` removed from `RangerAuthenticationProvider`
- [x] New `ugsync` launcher starts HA + metrics + `UserSyncService`
- [x] Docker usersync container stays up (`proc_rangerusersync` /
`UserSyncService`)
- [x] Docker PAM admin smoke (`ranger-admin-pam` on :6081,
`authentication_method=PAM`, OS user login)
- [ ] Release notes: remote Unix login **removed**, not disabled
---
## JIRA / Release Notes Template
**Summary:** Remove Unix remote authentication from Ranger — all four
modules plus Admin client code and config.
**User impact:**
- **UserGroupSync** (LDAP, file, Unix passwd/group sources): continues
unchanged.
- **Remote Unix Admin login** (Admin → usersync:5151): **removed** — migrate
to LDAP, Kerberos, or **local PAM on Admin** before upgrade.
- **Local PAM on Admin** (`PamLoginModule`): **unchanged in intent** — still
uses `/etc/pam.d` on the Admin host; not affected by deleting the usersync
listener.
- Usersync and Admin install layouts change; auth-only config and keystores
deleted.
**Migration:**
- Switch Admin authentication **before** upgrading if you use remote Unix
login today.
- Delete stale config: all `ranger.unixauth.*`, usersync port/SSL/validator
props, `AUTH_*` install keys, `unixauthservice.jks`.
- **Do not** add disable toggles — the code is gone.
---
## `authentication_method=UNIX` after removal (keep this value)
**`authentication_method=UNIX`** and **`ranger.authentication.method=UNIX`**
remain valid. After removal they mean **local PAM on the Ranger Admin host** —
not TCP to usersync.
| Setting | Before removal | After removal (this branch) |
|---------|----------------|----------------------------|
| `authentication_method=UNIX` + `ranger.pam.authentication.enabled=false`
(old default) | **Remote** login via `RemoteUnixLoginModule` → usersync:5151 |
**Removed** — migrate before upgrade |
| `authentication_method=UNIX` + `ranger.pam.authentication.enabled=true` |
Local `PamLoginModule` on Admin | Same as below |
| `authentication_method=UNIX` | (see above) | **Local** `PamLoginModule` on
Admin — `getPamAuthentication()` only |
| `authentication_method=PAM` | Local `PamLoginModule` on Admin | Same —
`getPamAuthentication()` |
| `setup_authentication.sh UNIX` | Injected `RemoteUnixLoginModule` or PAM
beans depending on config | Injects **`PamLoginModule`** via
`unix_bean_settings.xml` |
| `RangerAuthenticationProvider` | `getUnixAuthentication()` **or**
`getPamAuthentication()` | **`getPamAuthentication()` only** |
**Keep `UNIX` when:**
- Docker/dev installs that log into Admin with container OS accounts
(`dev-support/.../ranger-admin-install-*.properties` use
`authentication_method=UNIX`).
- On-prem installs where Admin runs on a host and operators log in with
**local Linux accounts via PAM on that Admin node**.
**Remove / migrate when:**
- Clusters that relied on **remote** Unix login (Admin on host A, password
check on usersync host B via `ranger.unixauth.*` and `passwordvalidator.path`).
Switch to LDAP, Kerberos, or **local PAM on Admin** before upgrading.
**Also removed from `install.properties` (remote client only — not the same
as local PAM):**
- `remoteLoginEnabled`, `authServiceHostName`, `authServicePort`,
`ranger_unixauth_*`, `ranger.unixauth.*` — configured the deleted TCP client
only.
- `ranger.usersync.passwordvalidator.path`, usersync port/SSL — configured
the deleted **listener** on usersync; unrelated to Admin `PamLoginModule`.
**Code references after removal:**
- `security-admin/scripts/setup_authentication.sh` — `UNIX` branch →
`PamLoginModule`
- `security-admin/scripts/setup.sh` —
`do_unix_authentication_method_setup()` when `authentication_method=UNIX`
- `RangerAuthenticationProvider` — `"UNIX".equalsIgnoreCase(...)` →
`getPamAuthentication()` (same as `PAM`)
- `security-admin/.../PamLoginModule.java` — libpam4j; config
**`ranger.pam.service`**
`PAM` as `ranger.authentication.method` and `UNIX` after removal both invoke
the same local `getPamAuthentication()` path; `UNIX` is kept for backward
compatibility with existing installs.
---
## File source sync config (`FileSourceUserGroupBuilder`)
The error message in `FileSourceUserGroupBuilder.buildUserGroupList()` was
updated from `unixauthservice.properties` to **`ranger-ugsync-site.xml`**. That
corrects a **misleading message** — it is not a new config migration.
| Question | Answer |
|----------|--------|
| Did file source ever read `unixauthservice.properties`? | **No.** Runtime
always used `UserGroupSyncConfig.getUserSyncFileSource()` → XML property
`ranger.usersync.filesource.file`. |
| What was `unixauthservice.properties` used for? | Legacy **policymgr
password** updates via `updatepolicymgrpassword.sh` (Java `.properties`
format). That script now writes **`ranger-ugsync-site.xml`** instead. |
| Where is file source configured? | **`ranger-ugsync-site.xml`**:
`ranger.usersync.filesource.file` (and optional
`ranger.usersync.filesource.text.delimiter`). |
| Docker file sync | `ugsync/scripts/setup.sh` sets source class + file path
when `ENABLE_FILE_SYNC_SOURCE=true`. |
| CLI override | Pass file path as argument to
`FileSourceUserGroupBuilder.main()`. |
**Config load order** (unchanged): `ranger-ugsync-default.xml` →
`core-site.xml` → `ranger-ugsync-site.xml`.
**Not in default `install.properties`:** file sync is optional; LDAP/unix
passwd sources use the normal install template. File source is typically
enabled in Docker or by editing `ranger-ugsync-site.xml` directly.
---
## History
| Item | Reference |
|------|-----------|
| CDPD-80522 disable-by-default | [CDH/ranger PR
#751](https://github.infra.cloudera.com/CDH/ranger/pull/751) — **not** the
Apache approach; we remove, not disable |
| Rate limiting (IP) | RANGER-5690 — **obsolete** once listener removed; do
not port to removal PR |
| Account throttling | PR #1102 — **obsolete** once listener removed |
| Docker PID grep | [Docker CI
section](#docker-ci-ranger-usersyncsh-pid-detection) |
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
