From: Alan T. DeKok Date: Sun, 8 Feb 2026 16:50:06 +0000 (-0500) Subject: print URL help for "Failed binding to socket" X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0e0bc233eaa42830c4442137144d412601447680;p=thirdparty%2Ffreeradius-server.git 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 46a3585fafa..c073079f44d 100644 --- 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 index 00000000000..5aeca099236 --- /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 54d337a4f93..3a04e1db862 100644 --- 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 ae494d770e0..5b8338fdb3c 100644 --- 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 b98bddb310f..6651a756c8d 100644 --- 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 61c9cbec1fe..0a41c54d681 100644 --- 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 d4df661a238..4cebb789db7 100644 --- 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 df8df2c1e69..26e9921d1da 100644 --- 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 4d976132069..c6abd459589 100644 --- 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 246973b7542..414024de246 100644 --- 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 3cc86af98ab..1da1b1c705b 100644 --- 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 1d3beda4256..ab1ca76f9f4 100644 --- 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; }