Repository navigation
docs(config): document auth.admin_pa_file - #526
arshilkxwork wants to merge 3 commits into
Conversation
Add the Server option from apache/hugegraph#3334 to the EN and CN config-option tables, the rest-server.properties example in the authentication guide, and the init-store check described in the hstore backend page.
bitflicker64
left a comment
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: yes. Summary: The pages describe auth.admin_pa_file as a first-startup-only setting, but the Server PR they document reads the file on every start with PD (hstore) and non-persistent backends, so following the docs and removing the secret after first boot stops the Server from restarting. The BOM stripping and the 4096-byte limit added later in the Server PR are also missing. Evidence: static comparison of this head (1667ee5) against apache/hugegraph#3334 at 128c0b3 (still open, not on master): ServerOptions.ADMIN_PA_FILE, StandardAuthenticator.initialAdminPassword/readAdminPasswordFile, GraphManager.loadMetaFromPD, InitStore.checkAdminBootstrapReachable. Precedence over auth.admin_pa and the init-store prompt, the trailing line break, the empty default and the init_store.enabled=false check all match that code. Site build not run.
| | auth.authenticator | | The class path of authenticator implementation. e.g., org.apache.hugegraph.auth.StandardAuthenticator, or a custom implementation. | | ||
| | auth.graph_store | hugegraph | The name of graph used to store authentication information, like users, only for org.apache.hugegraph.auth.StandardAuthenticator. | | ||
| | auth.admin_pa | pa | Used when the Server startup path initializes admin. Explicitly set a strong password before production deployment; the public default is `pa`. On local persistent backends, `init-store.sh` prompts for the initial password. | | ||
| | auth.admin_pa_file | | Path of a file holding the initial password for the built-in admin account. The file is read as raw UTF-8 with one trailing line break removed, so spaces, backslashes and non-ASCII characters need no properties escaping. When set, it takes precedence over `auth.admin_pa` and the `init-store.sh` password prompt. A missing, empty or non-UTF-8 file stops startup. Takes effect on first startup. | |
There was a problem hiding this comment.
Important: "Takes effect on first startup" is only half of the contract, and the missing half breaks restarts on PD/hstore. The password is applied once, but the file is read on every Server start when usePD=true (and on non-persistent backends). An operator who reads this row and removes the secret mount after the first boot gets a Server that refuses to start.
Evidence: apache/hugegraph#3334 head 128c0b3: GraphManager.loadMetaFromPD() (GraphManager.java:375-378) evaluates StandardAuthenticator.initialAdminPassword(conf) as the argument of initAdminUserIfNeeded(...), so the file is read before the admin-exists check, on every PD start. readAdminPasswordFile throws ConfigException when the file cannot be read. The option description in ServerOptions.ADMIN_PA_FILE says the same: "PD and non-persistent backends read it on every start, so keep it readable while this option is set."
Requested change: say that the password is only applied when the admin account is first created, but that with PD (hstore) and non-persistent backends the file is read on every start and must stay readable for as long as the option is set. The same sentence is needed in config-backend-hstore.md (line 179, "which is read at this point"), since that is the page for exactly the deployment that re-reads the file, and in the rest-server.properties comment in config-authentication.md.
There was a problem hiding this comment.
Fixed in 5d97063. The row now says the password is applied only when the admin is first created, and that PD (hstore) and non-persistent backends read the file on every start, so it has to stay readable while the option is set. The hstore init-store paragraph and the rest-server.properties comment say the same.
| | auth.authenticator | | The class path of authenticator implementation. e.g., org.apache.hugegraph.auth.StandardAuthenticator, or a custom implementation. | | ||
| | auth.graph_store | hugegraph | The name of graph used to store authentication information, like users, only for org.apache.hugegraph.auth.StandardAuthenticator. | | ||
| | auth.admin_pa | pa | Server 启动路径初始化内置 admin 账户时使用，默认值为公开的 `pa`，生产部署前必须显式设置强密码。本地持久化后端首次初始化由 `init-store.sh` 交互式读取密码。 | | ||
| | auth.admin_pa_file | | 存放内置 admin 账户初始密码的文件路径。文件按原始 UTF-8 读取，并去掉末尾的一个换行符，因此空格、反斜杠和非 ASCII 字符无需按 properties 语法转义。设置后优先于 `auth.admin_pa` 和 `init-store.sh` 的交互式密码输入。文件不存在、为空或不是合法 UTF-8 时启动失败。仅在首次启动时生效。 | |
There was a problem hiding this comment.
Important: "仅在首次启动时生效" (takes effect only on first startup) is stronger than the English row and contradicts the Server code for PD/hstore. The file is read on every start there, so deleting it after the first boot stops the Server from starting.
Evidence: apache/hugegraph#3334 head 128c0b3: GraphManager.loadMetaFromPD() (GraphManager.java:375-378) evaluates StandardAuthenticator.initialAdminPassword(conf) as the argument of initAdminUserIfNeeded(...), so the file is read before the admin-exists check, on every PD start. readAdminPasswordFile throws ConfigException when the file cannot be read. The option description in ServerOptions.ADMIN_PA_FILE says the same: "PD and non-persistent backends read it on every start, so keep it readable while this option is set."
Requested change: state that the password is only applied when the admin account is first created, and that with PD (hstore) and non-persistent backends the file is read on every start and must stay readable while the option is set. Apply the same to content/cn/docs/config/config-backend-hstore.md line 151 and the properties comment in content/cn/docs/config/config-authentication.md.
There was a problem hiding this comment.
Fixed in 5d97063 with the same wording as the EN row, and also in the CN hstore page and properties comment.
| | auth.authenticator | | The class path of authenticator implementation. e.g., org.apache.hugegraph.auth.StandardAuthenticator, or a custom implementation. | | ||
| | auth.graph_store | hugegraph | The name of graph used to store authentication information, like users, only for org.apache.hugegraph.auth.StandardAuthenticator. | | ||
| | auth.admin_pa | pa | Used when the Server startup path initializes admin. Explicitly set a strong password before production deployment; the public default is `pa`. On local persistent backends, `init-store.sh` prompts for the initial password. | | ||
| | auth.admin_pa_file | | Path of a file holding the initial password for the built-in admin account. The file is read as raw UTF-8 with one trailing line break removed, so spaces, backslashes and non-ASCII characters need no properties escaping. When set, it takes precedence over `auth.admin_pa` and the `init-store.sh` password prompt. A missing, empty or non-UTF-8 file stops startup. Takes effect on first startup. | |
There was a problem hiding this comment.
Minor: two behaviours of the current Server head are missing from this row and its CN counterpart. readAdminPasswordFile (StandardAuthenticator.java in apache/hugegraph#3334 at 128c0b3) also strips a leading UTF-8 BOM, and it rejects a file larger than 4096 bytes (MAX_ADMIN_PA_FILE_BYTES) with "is larger than 4096 bytes". The failure list here names only missing, empty and non-UTF-8 files. Both were added in the third commit of that PR, after this doc commit was written.
Requested change: mention the BOM alongside the trailing line break, and add the 4096-byte limit to the conditions that stop startup, in both the EN and CN rows (and the BOM in the two rest-server.properties comments, to match the shipped rest-server.properties).
There was a problem hiding this comment.
Fixed in 5d97063. Since your review, apache/hugegraph#3334 also gained 7ba00bd, which requires a regular file (symlinks followed) and caps the password at 72 UTF-8 bytes. The rows and both properties comments now cover the BOM, the 4096-byte file limit, the regular-file check and the 72-byte limit.
apache/hugegraph#3334 now requires a regular file, strips a leading BOM, and caps the file at 4096 bytes and the password at 72 UTF-8 bytes. Add those to the option rows and the rest-server.properties comments. The pages also called the option first-startup only. The password is applied only when the admin is created, but PD (hstore) and non-persistent backends read the file on every start, so removing it after the first boot stops the Server. Say so in the option rows, the properties comments and the hstore init-store paragraph.
bitflicker64
left a comment
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: yes. Summary: The option name, empty default, precedence, file checks (regular file, 4096-byte file limit, UTF-8, BOM and one trailing line break, 72-byte password limit), the init_store.enabled=false check and the read on every start with PD and non-persistent backends all match apache/hugegraph#3334 at 7ba00bd in both languages, and the three earlier review threads are addressed at this head. One gap remains: none of the three pages says which Server has the option, and a Server without it ignores the key and can create admin with the public default pa. Evidence: static comparison of this head (5d97063) against the apache/hugegraph#3334 diff at 7ba00bd (ServerOptions.ADMIN_PA_FILE, StandardAuthenticator.initialAdminPassword/readAdminPasswordFile, GraphManager.loadMetaFromPD, InitStore.checkAdminBootstrapReachable) and against apache/hugegraph master 0b7c0de (HugeConfig.addPropertyDirect, GraphManager.java:375-377); #3334 is still open. Site build not run.
| | auth.authenticator | | The class path of authenticator implementation. e.g., org.apache.hugegraph.auth.StandardAuthenticator, or a custom implementation. | | ||
| | auth.graph_store | hugegraph | The name of graph used to store authentication information, like users, only for org.apache.hugegraph.auth.StandardAuthenticator. | | ||
| | auth.admin_pa | pa | Used when the Server startup path initializes admin. Explicitly set a strong password before production deployment; the public default is `pa`. On local persistent backends, `init-store.sh` prompts for the initial password. | | ||
| | auth.admin_pa_file | | Path of a regular file (symlinks are followed) holding the initial password for the built-in admin account. The file is read as raw UTF-8 with a leading BOM and one trailing line break removed, so spaces, backslashes and non-ASCII characters need no properties escaping. The password may be at most 72 bytes in UTF-8, because the password hash ignores anything after that. When set, it takes precedence over `auth.admin_pa` and the `init-store.sh` password prompt. A file that is missing, unreadable, not a regular file, larger than 4096 bytes, not valid UTF-8, empty, or holding a password longer than 72 bytes stops `init-store.sh` or Server startup. The password is only applied when the admin account is first created, but with PD (hstore) and non-persistent backends the file is read on every start, so keep it readable for as long as the option is set. | |
There was a problem hiding this comment.
Important: this row, the rest-server.properties example in config-authentication.md and the init_store.enabled=false paragraph in config-backend-hstore.md present auth.admin_pa_file as available, in EN and CN, without saying which Server has it. No released Server and not even current master has the option (apache/hugegraph#3334 is still open), and a Server without it does not reject the key.
Evidence, apache/hugegraph master 0b7c0de: git grep admin_pa_file finds nothing. HugeConfig.addPropertyDirect only logs The config option '{}' is redundant, please ensure it has been registered for an unregistered key and carries on. GraphManager.loadMetaFromPD() (GraphManager.java:375-377) then calls initAdminUserIfNeeded(conf.get(ServerOptions.ADMIN_PA)), and the non-persistent path in checkBackendVersionOrExit reads ServerOptions.ADMIN_PA as well, whose default is pa. So an operator on such a Server who follows this row, sets only auth.admin_pa_file and leaves auth.admin_pa unset gets the admin account created with the public password pa on PD (hstore) with init-store enabled and on the memory backend, with one WARN line as the only sign. On local persistent backends init-store.sh falls back to the interactive prompt instead of reading the file. Merging this after #3334 does not cover readers on an older release. The other pages in this directory already mark version-bound behaviour (Since 1.7.0 ... in config-backend-hstore.md:80, applies only to images built from master in config-guide.md:39), and the hstore table this PR extends says its facts were checked at Server master 2f827d6, where the option does not exist.
Requested change: state the first Server version that supports auth.admin_pa_file (or that it is master-only until that release) in this row and in the CN row at content/cn/docs/config/config-option.md:72, and add the same note to the two properties comments and the two hstore paragraphs. Say there that an older Server ignores the option, so auth.admin_pa still has to be set on it.
There was a problem hiding this comment.
Fixed in 877f8f4. The option rows, both rest-server.properties comments and both hstore paragraphs, in EN and CN, now say auth.admin_pa_file is only in versions after 1.7.0, and that a 1.7.0 or earlier Server ignores the key with a warning and uses auth.admin_pa (default pa), so auth.admin_pa still has to be set there. I followed the "1.7.0 and earlier / later versions" wording already used in config-option.md instead of naming 1.8.0, since apache/hugegraph#3334 has not merged yet.
Servers up to 1.7.0 do not register the option. They log a warning for the unknown key and create the admin from auth.admin_pa, whose default is pa, or prompt in init-store. Say so in the option rows, the rest-server.properties comments and the hstore init-store paragraph, in EN and CN.
bitflicker64
left a comment
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: yes. Summary: The option name, empty default, precedence, file checks, the init_store.enabled=false check and the read on every start match apache/hugegraph#3334 in both languages, and the version note requested on 5d97063 is now in all six places. The fallback half of that note is wrong for part of the range it names: auth.admin_pa does not exist before 1.7.0, and 1.7.0 reads it only on the PD startup path. Evidence: static comparison of the full diff f0107c6..877f8f4 with the apache/hugegraph#3334 diff c1e7aba..f7f38ac (ServerOptions.ADMIN_PA_FILE, StandardAuthenticator.initialAdminPassword/readAdminPasswordFile, GraphManager.loadMetaFromPD/checkBackendVersionOrExit, InitStore.checkAdminBootstrapReachable) and with the release tags 1.7.0, 1.5.0, 1.3.0, 1.2.0 and 1.0.0 (git grep admin_pa, GraphManager.java, StandardAuthenticator.java, and HugeConfig.addPropertyDirect at 1.7.0 and 1.5.0). #3334 is still open and moved from 7ba00bd to f7f38ac after this head; the new commit only skips the file on the non-persistent path when auth.remote_url is set with the built-in authenticator, so the pages err on the safe side there. git diff --check is clean. Site build not run: the Build and deploy site workflow for this head is waiting for maintainer approval.
| | auth.authenticator | | The class path of authenticator implementation. e.g., org.apache.hugegraph.auth.StandardAuthenticator, or a custom implementation. | | ||
| | auth.graph_store | hugegraph | The name of graph used to store authentication information, like users, only for org.apache.hugegraph.auth.StandardAuthenticator. | | ||
| | auth.admin_pa | pa | Used when the Server startup path initializes admin. Explicitly set a strong password before production deployment; the public default is `pa`. On local persistent backends, `init-store.sh` prompts for the initial password. | | ||
| | auth.admin_pa_file | | Versions after 1.7.0 only. A 1.7.0 or earlier Server ignores this key, logging only a warning, and still uses `auth.admin_pa` (default `pa`) or the `init-store.sh` prompt, so set `auth.admin_pa` on those versions. Path of a regular file (symlinks are followed) holding the initial password for the built-in admin account. The file is read as raw UTF-8 with a leading BOM and one trailing line break removed, so spaces, backslashes and non-ASCII characters need no properties escaping. The password may be at most 72 bytes in UTF-8, because the password hash ignores anything after that. When set, it takes precedence over `auth.admin_pa` and the `init-store.sh` password prompt. A file that is missing, unreadable, not a regular file, larger than 4096 bytes, not valid UTF-8, empty, or holding a password longer than 72 bytes stops `init-store.sh` or Server startup. The password is only applied when the admin account is first created, but with PD (hstore) and non-persistent backends the file is read on every start, so keep it readable for as long as the option is set. | |
There was a problem hiding this comment.
Important: the fallback half of the version note added in 877f8f4 is wrong for part of the range it names. The earlier request on 5d97063 to say that auth.admin_pa still has to be set was checked against master only, not the release tags, and it does not hold for them: auth.admin_pa exists only from 1.7.0, and 1.7.0 reads it on the PD startup path only.
Evidence, apache/hugegraph release tags:
- 1.5.0, 1.3.0, 1.2.0, 1.0.0:
git grep admin_pa <tag>finds nothing, soauth.admin_pais as unknown there asauth.admin_pa_file(at 1.5.0HugeConfig.addPropertyDirectlogs the sameThe config option '{}' is redundantwarning for it). The admin password comes from theinit-store.shprompt (StandardAuthenticator.initAdminUser()callsinputPassword()), or fromauth.admin_tokenon the memory backend (GraphManager.java:439-441at 1.5.0). - 1.7.0: the only read of
ServerOptions.ADMIN_PAis inGraphManager.loadMetaFromPD()(GraphManager.java:364). On the memory backend, the only non-persistent one,checkBackendVersionOrExitstill runsinitAdminUser(config.get(ServerOptions.AUTH_ADMIN_TOKEN))(GraphManager.java:1614-1616), andauth.admin_tokendefaults to the public162f7848-0b6d-4faf-b557-3a0797869c55(ServerOptions.java:487). That path moved toauth.admin_pain a93cc218d (#2927, 2026-01-04), which no release tag contains.
So on 1.7.0 with the memory backend and auth on, an operator who follows this row and sets auth.admin_pa still gets an admin whose password is the auth.admin_token value. The sentence is right for 1.7.0 with PD (hstore).
Requested change: in this row and the CN row (content/cn/docs/config/config-option.md:72), replace the fallback sentence with what the releases do, for example: "Versions after 1.7.0 only. A 1.7.0 or earlier Server ignores this key, logging only a warning, and creates admin as before: from the init-store.sh prompt on local persistent backends, from auth.admin_pa (default pa) on 1.7.0 with PD (hstore), and from auth.admin_token (public default) on the memory backend. auth.admin_pa does not exist before 1.7.0." In the two properties comments (content/en/docs/config/config-authentication.md:103, content/cn/docs/config/config-authentication.md:98), keep "older Servers ignore this key" and point to the option table instead of "still need auth.admin_pa". In the two hstore paragraphs (content/en/docs/config/config-backend-hstore.md:183, content/cn/docs/config/config-backend-hstore.md:151), change "1.7.0 or earlier" / "1.7.0 及更早版本" to 1.7.0, since those paragraphs are about PD.
|
Closing together with apache/hugegraph#3334, which is deferred (apache/hugegraph#3334 (comment)). Thanks @bitflicker64 for the reviews. Your last point was right: the fallback note I added in 877f8f4 is wrong for releases before 1.7.0, which have no |
2 participants
Docs for apache/hugegraph#3334 (apache/hugegraph#3334), which adds the Server option
auth.admin_pa_file.auth.admin_pagoes through the properties grammar: the value is trimmed, backslashes are unescaped and the file is decoded as ISO-8859-1. The new option names a regular file (symlinks are followed) that the Server reads as raw UTF-8, dropping a leading BOM and one trailing line break. The file may be at most 4096 bytes and the password at most 72 UTF-8 bytes. When set, it takes precedence overauth.admin_paand theinit-store.shpassword prompt. The password is applied only when the admin account is first created, but PD (hstore) and non-persistent backends read the file on every start, so it has to stay readable while the option is set.Updated in both EN and CN:
config-option.md: a row forauth.admin_pa_fileright afterauth.admin_pa.config-authentication.md: a commentedauth.admin_pa_fileline underauth.admin_pain therest-server.propertiesexample.config-backend-hstore.md: withinit_store.enabled=false, the explicit-password check now also acceptsauth.admin_pa_fileand reads the file at that point. The page also says the Server reads the file again on every start with PD.Each page says the option exists only in versions after 1.7.0. An older Server ignores the key with a warning and falls back to
auth.admin_pa(defaultpa), so the pages tell readers to keep settingauth.admin_pathere.The pages match apache/hugegraph#3334 at 7ba00bd. This should merge after that PR, since no released Server has the option yet.
I ran
git diff --check. I did not build the site locally.