SSH issue stemming from missing documentation #14076

New Issue

GiteaMirror · 2025-11-02T11:02:13-06:00

GiteaMirror commented

2025-11-02 11:02:13 -06:00

Originally created by @tjb1982 on GitHub (Jan 31, 2025).

Description

I followed the documentation for preparing the environment which includes this

# On Ubuntu/Debian:
adduser \
   --system \
   --shell /bin/bash \
   --gecos 'Git Version Control' \
   --group \
   --disabled-password \
   --home /home/git \
   git

I created a user named "gitea" and I was installing on a Debian server. I couldn't ssh authenticate with this user. All of the file permissions up and down were correct, sshd configuration in good shape, etc. Following the log, like sudo journalctl --unit ssh --pager-end --follow showed that the problem from the sshd server was:

sshd[152357]: User gitea not allowed because account is locked

My sshd_config disallows password authentication, so I'm not sure why having a password on the user matters, but it apparently the user needs some sort of password in order to not be locked. This was solved by creating an unusable password for the gitea user like this:

sudo usermod -p '*' gitea

(courtesy of this SO answer)

Change the account to have no password, but be unlocked. An account has no password if the password hash in the password database is not the hash of any string. Traditionally, a one-character string such as * or ! is used for that.

Gitea Version

1.23.1 built with GNU Make 4.3, go1.23.4 : bindata, sqlite, sqlite_unlock_notify

Can you reproduce the bug on the Gitea demo site?

No

Log Gist

No response

Screenshots

No response

Git Version

No response

Operating System

Debian GNU/Linux 12 (bookworm)

How are you running Gitea?

Installation from binary, running as service.

Database

SQLite

Originally created by @tjb1982 on GitHub (Jan 31, 2025). ### Description I followed the documentation for [preparing the environment](https://docs.gitea.com/installation/install-from-binary#prepare-environment) which includes this ``` # On Ubuntu/Debian: adduser \ --system \ --shell /bin/bash \ --gecos 'Git Version Control' \ --group \ --disabled-password \ --home /home/git \ git ``` I created a user named "gitea" and I was installing on a Debian server. I couldn't ssh authenticate with this user. All of the file permissions up and down were correct, sshd configuration in good shape, etc. Following the log, like `sudo journalctl --unit ssh --pager-end --follow` showed that the problem from the sshd server was: ``` sshd[152357]: User gitea not allowed because account is locked ``` My sshd_config disallows password authentication, so I'm not sure why having a password on the user matters, but it apparently the user needs some sort of password in order to not be locked. This was solved by creating an unusable password for the `gitea` user like this: ``` sudo usermod -p '*' gitea ``` (courtesy of [this SO answer](https://unix.stackexchange.com/a/193131/40407)) > Change the account to have no password, but be unlocked. An account has no password if the password hash in the password database is not the hash of any string. Traditionally, a one-character string such as * or ! is used for that. ### Gitea Version 1.23.1 built with GNU Make 4.3, go1.23.4 : bindata, sqlite, sqlite_unlock_notify ### Can you reproduce the bug on the Gitea demo site? No ### Log Gist _No response_ ### Screenshots _No response_ ### Git Version _No response_ ### Operating System Debian GNU/Linux 12 (bookworm) ### How are you running Gitea? Installation from binary, running as service. ### Database SQLite

GiteaMirror added the docs-update-needed type/bug labels 2025-11-02 11:02:13 -06:00

GiteaMirror commented

2025-11-02 11:02:14 -06:00

@wxiaoguang commented on GitHub (Jan 31, 2025):

Some SO answers also mention that UsePAM yes affects the "locked" user behavior?

Also see this: https://github.com/camptocamp/puppet-accounts/issues/35#issuecomment-206673240

I've just checked my sshd_config, It had UsePAM no which refuse my ssh connection. Enable PAM help to resolve this issue.

Basically, if we use UsePAM no and shadow file:
* `my-username:!:16897:0:99999:7:::` NOT able to login.
* `my-username:*:16897:0:99999:7:::` able to login.
My test is on Ubuntu 14.04.

@wxiaoguang commented on GitHub (Jan 31, 2025): Some SO answers also mention that `UsePAM yes` affects the "locked" user behavior? ---- Also see this: https://github.com/camptocamp/puppet-accounts/issues/35#issuecomment-206673240 > I've just checked my `sshd_config`, It had `UsePAM no` which refuse my ssh connection. Enable `PAM` help to resolve this issue. > > Basically, if we use `UsePAM no` and shadow file: > > * `my-username:!:16897:0:99999:7:::` NOT able to login. > * `my-username:*:16897:0:99999:7:::` able to login. > > My test is on Ubuntu 14.04.

GiteaMirror commented

2025-11-02 11:02:14 -06:00

@tjb1982 commented on GitHub (Jan 31, 2025):

I think UsePAM no is more secure and it seems to work fine for my setup.

@tjb1982 commented on GitHub (Jan 31, 2025): I think `UsePAM no` is more secure and it seems to work fine for my setup.

GiteaMirror commented

2025-11-02 11:02:14 -06:00

@wxiaoguang commented on GitHub (Jan 31, 2025):

Yup, I am just trying to figure out the root reason of the problem. And I have added docs-update-needed label, I think the documents could be updated: https://gitea.com/gitea/docs/

Do you have suggestions about how to improve the document properly?

@wxiaoguang commented on GitHub (Jan 31, 2025): Yup, I am just trying to figure out the root reason of the problem. And I have added `docs-update-needed` label, I think the documents could be updated: https://gitea.com/gitea/docs/ Do you have suggestions about how to improve the document properly?

GiteaMirror commented

2025-11-02 11:02:14 -06:00

@tjb1982 commented on GitHub (Jan 31, 2025):

I think the issue stems from adduser --disabled-passwd which leaves the user without a password set at all, and that seems to be equivalent to being locked out from too many failed login attempts, so there might just need to be some verbiage in a quote/warning div that says something like

The adduser command with the --disabled-passwd flag will leave the user without a password, effectively locked out of the system, meaning ssh login will result in "permission denied." One way to get around this is to set the user's password like usermod -p '*' username, which will change the accound to have no password, but be unlocked. See, e.g., this discussion on unix.stackexchange for details.

Edit it may not be totally obvious what's going on here. A user's password is expected to live in the password database in encrypted form, but the usermod's -p flag expects the string you pass to it to be that encrypted form, not the cleartext form someone would type into a terminal. This means that if you pass a single char like '*' it will store that single char in the password database as that literal char, rather than the hashed version of it. No string hashes to '*' so effectively there is no string you could use for a password to log in as that user. Merely having a password apparently unlocks the user's account in this case. And sshd with PasswordAuthentication no never cared about the password, but it saw the user as locked, so it stopped there, even if it was asked to auth via public key.

The relevant doc from man usermod:

       -p, --password PASSWORD
           defines a new password for the user. PASSWORD is expected to be encrypted, as returned by crypt (3).

           Note: Avoid this option on the command line because the password (or encrypted password) will be visible by users listing the processes.

           The password will be written in the local /etc/passwd or /etc/shadow file. This might differ from the password database configured in your PAM configuration.

           You should make sure the password respects the system's password policy.

This might be why UsePAM yes fixes this, because PAM may use a different database or handle it in a different way). But as I said, I think it's fairly common to disable PAM for security reasons.

@tjb1982 commented on GitHub (Jan 31, 2025): I think the issue stems from `adduser --disabled-passwd` which leaves the user without a password set at all, and that seems to be equivalent to being locked out from too many failed login attempts, so there might just need to be some verbiage in a quote/warning div that says something like > The `adduser` command with the `--disabled-passwd` flag will leave the user without a password, effectively locked out of the system, meaning ssh login will result in "permission denied." One way to get around this is to set the user's password like `usermod -p '*' username`, which will change the accound to have no password, but be unlocked. See, e.g., [this discussion on unix.stackexchange](https://unix.stackexchange.com/a/193131/40407) for details. **Edit** it may not be totally obvious what's going on here. A user's password is expected to live in the password database in encrypted form, but the `usermod`'s `-p` flag expects the string you pass to it to be that encrypted form, not the cleartext form someone would type into a terminal. This means that if you pass a single char like `'*'` it will store that single char in the password database as that literal char, rather than the hashed version of it. No string hashes to `'*'` so effectively there is no string you could use for a password to log in as that user. Merely having a password apparently unlocks the user's account in this case. And sshd with `PasswordAuthentication no` never cared about the password, but it saw the user as locked, so it stopped there, even if it was asked to auth via public key. The relevant doc from `man usermod`: ``` -p, --password PASSWORD defines a new password for the user. PASSWORD is expected to be encrypted, as returned by crypt (3). Note: Avoid this option on the command line because the password (or encrypted password) will be visible by users listing the processes. The password will be written in the local /etc/passwd or /etc/shadow file. This might differ from the password database configured in your PAM configuration. You should make sure the password respects the system's password policy. ``` This might be why `UsePAM yes` fixes this, because PAM may use a different database or handle it in a different way). But as I said, I think it's fairly common to disable PAM for security reasons.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#14076