login-common: Add comments

diff --git a/src/login-common/client-common.c b/src/login-common/client-common.c
index 8194c144d1e8428ce87087e0617c453985e5fe4d..6f576560e4f530e6586c4de61319ee0043c912c2 100644 (file)
--- a/src/login-common/client-common.c
+++ b/src/login-common/client-common.c
@@ -1139,6 +1139,11 @@ const char *client_get_extra_disconnect_reason(struct client *client)
        if (client->auth_process_comm_fail)
                return "auth process communication failure";
 
+       /* The reasons below are returned only when there is a single
+          authentication attempt. The main reason is to avoid confusion in
+          case the client sends tons of auth attempts and disconnection just
+          happens to be on the last attempt. In that case it's more important
+          to know the total number of auth attempts instead. */
        if (client->auth_client_continue_pending && client->auth_attempts == 1) {
                return t_strdup_printf("client didn't finish SASL auth, "
                                       "waited %u secs", auth_secs);
@@ -1154,10 +1159,16 @@ const char *client_get_extra_disconnect_reason(struct client *client)
        if (client->auth_aborted_by_client && client->auth_attempts == 1)
                return "auth aborted by client";
 
-       if (client->auth_nologin_referral)
+       if (client->auth_nologin_referral) {
+               /* Referral was sent to the connecting client, which is
+                  expected to be a trusted Dovecot proxy. There should be no
+                  further auth attempts. */
                return "auth referral";
-       if (client->proxy_auth_failed)
+       }
+       if (client->proxy_auth_failed) {
+               /* Authentication to the next hop failed. */
                return "proxy dest auth failed";
+       }
        if (client->auth_successes > 0) {
                return t_strdup_printf("internal failure, %u successful auths",
                                       client->auth_successes);

diff --git a/src/login-common/client-common.h b/src/login-common/client-common.h
index 0d4bda8557b1b232ca6fc30709b28738b5fa450a..048e51f7d0629554b9ca0bae7bd2050dfe098362 100644 (file)
--- a/src/login-common/client-common.h
+++ b/src/login-common/client-common.h
@@ -197,6 +197,8 @@ struct client {
 
        char *auth_mech_name;
        enum sasl_server_auth_flags auth_flags;
+       /* Auth request set while the client is authenticating.
+          During this time authenticating=TRUE also. */
        struct auth_client_request *auth_request;
        struct auth_client_request *reauth_request;
        string_t *auth_response;
@@ -207,6 +209,9 @@ struct client {
        struct anvil_request *anvil_request;
 
        unsigned int master_auth_id;
+       /* Tag that can be used with login_client_request_abort() to abort
+          sending client fd to mail process. authenticating is always TRUE
+          while this is non-zero. */
        unsigned int master_tag;
        sasl_server_callback_t *sasl_callback;
 
@@ -257,6 +262,10 @@ struct client {
        bool connection_trusted:1;
        bool ssl_servername_settings_read:1;
        bool banner_sent:1;
+       /* Authentication is going on. This is set a bit before auth_request is
+          created, and it can fail early e.g. due to unknown SASL mechanism.
+          Also this is still TRUE while the client fd is being sent to the
+          mail process (master_tag != 0). */
        bool authenticating:1;
        /* SASL authentication is waiting for client to send a continuation */
        bool auth_client_continue_pending:1;