print URL help for "Failed binding to socket"

and add preliminary page with a description

diff --git a/doc/antora/modules/troubleshooting/nav.adoc b/doc/antora/modules/troubleshooting/nav.adoc
index 46a3585fafa379b01b8c1b7c691f6cfd6bf46204..c073079f44d3a6467fec38a5f563d1184515299e 100644 (file)
--- a/doc/antora/modules/troubleshooting/nav.adoc
+++ b/doc/antora/modules/troubleshooting/nav.adoc
@@ -2,6 +2,9 @@
 
 ** xref:network/index.adoc[Network Errors]
 
+*** Server does not start
+**** xref:network/bind.adoc[Failed binding to socket]
+
 *** Common Errors
 **** xref:network/unknown_packet_code.adoc[Unknown packet code]
 **** xref:network/unexpected_request_code.adoc[Unexpected request code]

diff --git a/doc/antora/modules/troubleshooting/pages/network/bind.adoc b/doc/antora/modules/troubleshooting/pages/network/bind.adoc
new file mode 100644 (file)
index 0000000..5aeca09
--- /dev/null
+++ b/doc/antora/modules/troubleshooting/pages/network/bind.adoc
@@ -0,0 +1,21 @@
+= Failed binding to socket
+
+This error message is produced when the server cannot open a socket on
+the specified port.  There are a few reasons why this can happen, but
+the most common one is that there is already another instance of
+FreeRADIUS running.
+
+**Cause:** You are trying to run the server in
+xref:ROOT:debugging/radiusd_X.adoc[debug mode], without stopping the
+server that is running in the background.
+
+**Action:** Stop the server which is running in the background, and
+you can then run it in debug mode.
+
+**Cause:** The server does not have permission to open the given socket/port.
+
+**Action:** Check that the server has the correct UID/GID permissions.
+
+**Action:** Check that something like SeLinux is not preventing the
+server from opening sockets.
+

diff --git a/doc/antora/modules/troubleshooting/pages/network/index.adoc b/doc/antora/modules/troubleshooting/pages/network/index.adoc
index 54d337a4f93821a84c4249d0cea4a19e61023c61..3a04e1db86230e9699d7dab510f6e324cffcb7c9 100644 (file)
--- a/doc/antora/modules/troubleshooting/pages/network/index.adoc
+++ b/doc/antora/modules/troubleshooting/pages/network/index.adoc
@@ -4,11 +4,20 @@ If the server isn't processing packets, this is due to two common
 problems.  Either it is either not receiving packets, or else it
 receives a packet and discards it with a complaint.  Both situations
 can be solved by running the server in
-xref:ROOT:debugging/radiusd_X.adoc[debugging] mode.
+xref:ROOT:debugging/radiusd_X.adoc[debug mode].
+
+== Server does not start
+
+If the server does not start, it prints a descriptive message to the
+log files, or to the terminal window.  The common errors are listed
+below.
+
+* xref:network/bind.adoc[Failed binding to socket]
 
 == Not Receiving Packets
 
-When the server is started in debugging mode, the last line it prints is:
+When the server successfully starts in debugging mode, the last line
+it prints is:
 
 [source,text]
 ----
@@ -54,7 +63,7 @@ All of these should be checked beforing checking any FreeRADIUS configuration.
 
 When the server discards packets for a particular reason, it gives a
 descriptive error messages when running in
-xref:ROOT:debugging/radiusd_X.adoc[debugging] mode.  The errors are
+xref:ROOT:debugging/radiusd_X.adoc[debug mode].  The errors are
 not sent to the normal log file, because that could allow attackers to
 DoS the server.
 

diff --git a/src/lib/util/version.h b/src/lib/util/version.h
index ae494d770e0c206613ad6d188f9c1abc84610bfb..5b8338fdb3cb20029be227fc2807cf14c7ddc33b 100644 (file)
--- a/src/lib/util/version.h
+++ b/src/lib/util/version.h
@@ -87,6 +87,7 @@ extern "C" {
 #define DOC_ROOT_URL "https://www.freeradius.org/documentation/freeradius-server/" STRINGIFY(RADIUSD_DOC_VERSION)
 #define DOC_KEYWORD_URL(_x) DOC_ROOT_URL "/reference/unlang/" STRINGIFY(_x) ".html"
 #define DOC_KEYWORD_REF(_x) "For more information, please see " DOC_KEYWORD_URL(_x)
+#define DOC_ROOT_REF(_x) "For more information, please see " STRINGIFY(_x) ".html"
 
 /*
  *     Version check.

diff --git a/src/listen/bfd/proto_bfd_udp.c b/src/listen/bfd/proto_bfd_udp.c
index b98bddb310fc274c4f72fe48e42ba8eeaa49a44b..6651a756c8d6475f3d063427ea5c691bd2b72007 100644 (file)
--- a/src/listen/bfd/proto_bfd_udp.c
+++ b/src/listen/bfd/proto_bfd_udp.c
@@ -312,6 +312,7 @@ static int mod_open(fr_listen_t *li)
        if (fr_socket_bind(sockfd, inst->interface, &ipaddr, &port) < 0) {
                close(sockfd);
                cf_log_err(li->cs, "Failed binding socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }
 

diff --git a/src/listen/dhcpv4/proto_dhcpv4_udp.c b/src/listen/dhcpv4/proto_dhcpv4_udp.c
index 61c9cbec1fe63ec557e8ab0881b4d0ce61e262e3..0a41c54d681882071fa0e73c35725d333a46ea79 100644 (file)
--- a/src/listen/dhcpv4/proto_dhcpv4_udp.c
+++ b/src/listen/dhcpv4/proto_dhcpv4_udp.c
@@ -718,6 +718,7 @@ static int mod_open(fr_listen_t *li)
        if (rcode < 0) {
                close(sockfd);
                cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }
        if (inst->interface) li->app_io_addr->inet.src_ipaddr.scope_id = ipaddr.scope_id;

diff --git a/src/listen/dhcpv6/proto_dhcpv6_udp.c b/src/listen/dhcpv6/proto_dhcpv6_udp.c
index d4df661a23831558018d5d48c514bba7a7a25892..4cebb789db763ae2adcd8c9a4d7f37bca759f328 100644 (file)
--- a/src/listen/dhcpv6/proto_dhcpv6_udp.c
+++ b/src/listen/dhcpv6/proto_dhcpv6_udp.c
@@ -328,6 +328,7 @@ static int mod_open(fr_listen_t *li)
        rad_suid_down();
        if (rcode < 0) {
                cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
        close_error:
                close(sockfd);
                goto error;

diff --git a/src/listen/dns/proto_dns_udp.c b/src/listen/dns/proto_dns_udp.c
index df8df2c1e69adad7a87cd3bf66aee2e854a6ae61..26e9921d1da582ea4b438e30feebac40392d5439 100644 (file)
--- a/src/listen/dns/proto_dns_udp.c
+++ b/src/listen/dns/proto_dns_udp.c
@@ -294,8 +294,9 @@ static int mod_open(fr_listen_t *li)
        rcode = fr_socket_bind(sockfd, inst->interface, &ipaddr, &port);
        rad_suid_down();
        if (rcode < 0) {
-               cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
                close(sockfd);
+               cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }
 

diff --git a/src/listen/radius/proto_radius_tcp.c b/src/listen/radius/proto_radius_tcp.c
index 4d9761320691d8c6cbaf094d4809e2f787581e0a..c6abd459589ba6acdccaf4d1c038d07b1e8a972a 100644 (file)
--- a/src/listen/radius/proto_radius_tcp.c
+++ b/src/listen/radius/proto_radius_tcp.c
@@ -350,6 +350,7 @@ static int mod_open(fr_listen_t *li)
        if (fr_socket_bind(sockfd, inst->interface, &ipaddr, &port) < 0) {
                close(sockfd);
                cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }
 

diff --git a/src/listen/radius/proto_radius_udp.c b/src/listen/radius/proto_radius_udp.c
index 246973b7542540eb9796e11b76a1f89139e6697f..414024de2466bb49dc15e1be0e963e2f8ecf0446 100644 (file)
--- a/src/listen/radius/proto_radius_udp.c
+++ b/src/listen/radius/proto_radius_udp.c
@@ -355,6 +355,7 @@ static int mod_open(fr_listen_t *li)
        if (fr_socket_bind(sockfd, inst->interface, &ipaddr, &port) < 0) {
                close(sockfd);
                cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }
 

diff --git a/src/listen/tacacs/proto_tacacs_tcp.c b/src/listen/tacacs/proto_tacacs_tcp.c
index 3cc86af98ab3d0a287ae5fe2d91fbb68e1d3e6c3..1da1b1c705b397c0651f7f536c1bb870d6bb0b68 100644 (file)
--- a/src/listen/tacacs/proto_tacacs_tcp.c
+++ b/src/listen/tacacs/proto_tacacs_tcp.c
@@ -374,6 +374,7 @@ static int mod_open(fr_listen_t *li)
        if (fr_socket_bind(sockfd, inst->interface, &ipaddr, &port) < 0) {
                close(sockfd);
                cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }
 

diff --git a/src/listen/vmps/proto_vmps_udp.c b/src/listen/vmps/proto_vmps_udp.c
index 1d3beda4256616e735244c3645a5a72420898a4f..ab1ca76f9f407927d2a7290ddb4e626c5e47ebb7 100644 (file)
--- a/src/listen/vmps/proto_vmps_udp.c
+++ b/src/listen/vmps/proto_vmps_udp.c
@@ -313,6 +313,7 @@ static int mod_open(fr_listen_t *li)
        if (fr_socket_bind(sockfd, inst->interface, &ipaddr, &port) < 0) {
                close(sockfd);
                cf_log_err(li->cs, "Failed binding to socket - %s", fr_strerror());
+               cf_log_err(li->cs, DOC_ROOT_REF(troubleshooting/network/bind));
                goto error;
        }