diff --git a/.github/workflows/quick.yaml b/.github/workflows/quick.yaml index 6a9766ad96d..05b57992d69 100644 --- a/.github/workflows/quick.yaml +++ b/.github/workflows/quick.yaml @@ -36,8 +36,11 @@ jobs: steps: - name: Install prerequisite packages run: | + # required for "apt-get build-dep" to work + sudo sed --in-place -E 's/# (deb-src.*updates main)/ \1/g' /etc/apt/sources.list sudo apt-get --quiet=2 update - sudo apt-get --quiet=2 install libtool-bin + sudo apt-get --quiet=2 build-dep squid + sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin pandoc - name: Setup a nodejs environment uses: actions/setup-node@v4 @@ -127,7 +130,7 @@ jobs: sudo sed --in-place -E 's/# (deb-src.*updates main)/ \1/g' /etc/apt/sources.list sudo apt-get --quiet=2 update sudo apt-get --quiet=2 build-dep squid - sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin ${{ matrix.compiler.CC }} ccache + sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin pandoc ${{ matrix.compiler.CC }} ccache - name: Checkout sources uses: actions/checkout@v4 @@ -163,7 +166,7 @@ jobs: sudo sed --in-place -E 's/# (deb-src.*updates main)/ \1/g' /etc/apt/sources.list sudo apt-get --quiet=2 update sudo apt-get --quiet=2 build-dep squid - sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin + sudo apt-get --quiet=2 install linuxdoc-tools libtool-bin pandoc - name: Checkout repository uses: actions/checkout@v4 diff --git a/configure.ac b/configure.ac index 2cbd317cf05..9237cf110ab 100644 --- a/configure.ac +++ b/configure.ac @@ -143,6 +143,9 @@ AC_PATH_PROG(AR, ar, $FALSE) AR_R="$AR r" AC_SUBST(AR_R) +AC_PATH_PROG(PANDOC, pandoc, $FALSE) +AM_CONDITIONAL(ENABLE_PANDOC_DOC, test "x${ac_cv_path_PANDOC}" != "x$FALSE") + AC_PATH_PROG(LINUXDOC, linuxdoc, $FALSE) AM_CONDITIONAL(ENABLE_RELEASE_DOCS, test "x${ac_cv_path_LINUXDOC}" != "x$FALSE") diff --git a/doc/manuals/Substitute.am b/doc/manuals/Substitute.am index 948896b5612..245440cdd12 100644 --- a/doc/manuals/Substitute.am +++ b/doc/manuals/Substitute.am @@ -17,6 +17,7 @@ SUBSTITUTE=sed "\ s%@SYSCONFDIR@%$(sysconfdir)%g;\ " -## Example of how to substitute: -## squid.8: $(srcdir)/squid.8.in Makefile -## $(SUBSTITUTE) < $(srcdir)/squid.8.in > $@ +.md.8: + $(SUBSTITUTE) < $(srcdir)/`basename $<` | \ + $(PANDOC) -t man -f gfm -s -o $@ + diff --git a/src/Common.am b/src/Common.am index ff2b736b427..0970a8b7bd0 100644 --- a/src/Common.am +++ b/src/Common.am @@ -70,4 +70,5 @@ COMPAT_LIB = $(top_builddir)/compat/libcompatsquid.la $(LIBPROFILER) ## Some helpers are written in Perl and need the local shell defined properly subst_perlshell = sed -e 's,[@]PERL[@],$(PERL),g' <$(srcdir)/$@.pl.in >$@ || ($(RM) -f $@ ; exit 1) +include $(top_srcdir)/doc/manuals/Substitute.am include $(top_srcdir)/src/TestHeaders.am diff --git a/src/Makefile.am b/src/Makefile.am index cfd26b31867..3c27a9b5256 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -7,6 +7,13 @@ include $(top_srcdir)/src/Common.am +dist_doc_DATA = squid.md + +if ENABLE_PANDOC_DOC +man_MANS = squid.8 +CLEANFILES += squid.8 +endif + DNSSOURCE = \ dns_internal.cc @@ -689,15 +696,6 @@ cf.data: cf.data.pre Makefile repl_modules.cc: repl_modules.sh Makefile $(SHELL) $(srcdir)/repl_modules.sh $(REPL_POLICIES) > repl_modules.cc -include $(top_srcdir)/doc/manuals/Substitute.am - -squid.8: $(srcdir)/squid.8.in Makefile - $(SUBSTITUTE) < $(srcdir)/squid.8.in > $@ - -man_MANS = squid.8 -EXTRA_DIST += squid.8.in -CLEANFILES += squid.8 - install-data-local: install-sysconfDATA install-dataDATA @if test -f $(DESTDIR)$(DEFAULT_MIME_TABLE) ; then \ echo "$@ will not overwrite existing $(DESTDIR)$(DEFAULT_MIME_TABLE)" ; \ diff --git a/src/security/cert_generators/file/Makefile.am b/src/security/cert_generators/file/Makefile.am index 070dc95e608..117494922c6 100644 --- a/src/security/cert_generators/file/Makefile.am +++ b/src/security/cert_generators/file/Makefile.am @@ -6,7 +6,6 @@ ## include $(top_srcdir)/src/Common.am -include $(top_srcdir)/doc/manuals/Substitute.am security_file_certgen.8: $(srcdir)/security_file_certgen.8.in Makefile $(SUBSTITUTE) < $(srcdir)/security_file_certgen.8.in > $@ diff --git a/src/squid.8.in b/src/squid.8.in deleted file mode 100644 index c8c76cebf59..00000000000 --- a/src/squid.8.in +++ /dev/null @@ -1,289 +0,0 @@ -.if !'po4a'hide' .TH squid 8 -. -.SH NAME -squid \- HTTP web proxy caching server -. -.SH SYNOPSIS -.if !'po4a'hide' .B squid -.if !'po4a'hide' .B [\-dhisrvzCFNRSVYX] -.if !'po4a'hide' .B [\--foreground] -.if !'po4a'hide' .B [\-l -facility -.if !'po4a'hide' .B ] [\-f -config\-file -.if !'po4a'hide' .B ] [\-[au] -port -.if !'po4a'hide' .B ] [\-k -signal -.if !'po4a'hide' .B ] [\-n -service\-name -.if !'po4a'hide' .B ] [\-O -command\-line -.if !'po4a'hide' .B ] -. -.SH DESCRIPTION -.PP -.B squid -is a high\-performance proxy caching server for web clients, -supporting FTP, ICAP, ICP, HTCP and HTTP data objects. -Unlike traditional caching software, -Squid handles all requests in a single, non-blocking process. -.PP -Squid keeps meta data and especially hot objects cached in RAM, -caches DNS lookups, supports non\-blocking DNS lookups, and implements -negative caching of failed requests. -.PP -Squid supports SSL, extensive access controls, and full request logging. -By using the lightweight Internet Cache Protocols ICP, HTCP or CARP, -Squid caches can be arranged in a hierarchy or mesh for additional -bandwidth savings. -.PP -Squid consists of a main server program -.B squid -, some optional programs for -custom processing and authentication, and some management and client -tools. When squid starts up, it spawns a configurable number of -helper processes, each of which can perform parallel lookups. -This reduces the amount of time the cache waits for results. -.PP -Squid is derived from the ARPA\-funded Harvest Project. -.PP -This manual page only lists the command line arguments. -For details on how to configure Squid see the file -.BI @SYSCONFDIR@/squid.conf.documented, -the Squid wiki FAQ and examples at https://wiki.squid-cache.org/ , -or the configuration manual on the Squid home page -.if !'po4a'hide' http://www.squid-cache.org/Doc/config/ -. -.SH OPTIONS -.if !'po4a'hide' .TP 12 -.if !'po4a'hide' .B "\-a port" -Specify HTTP port number where Squid should listen for requests, in addition to any -.B http_port -specifications in -.B squid.conf -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-C -Do not catch fatal signals. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-d level" -Write debugging to stderr also. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-f file" -Use the given config-file instead of -.B @SYSCONFDIR@/squid.conf . -If the file name starts with a -.B ! -or -.B | -then it is assumed to be an external command or command line. -Can for example be used to pre\-process the configuration before it is being read by Squid. -To facilitate this Squid also understands the common #line notion to indicate the real source file. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-F -Don't serve any requests until store is rebuilt. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-h -Print help message. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-i -Install as a Windows Service (see -.B \-n -option). -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-k reconfigure | rotate | shutdown | interrupt | kill | debug | check | parse" -Parse configuration file, then send signal to running copy -(except -.B "\-k parse" -) and exit. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-l facility" -Use specified syslog facility. Implies -.B \-s -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-n name" -Specify Windows Service name to use for service operations, default is: -.B Squid -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-N -No daemon mode. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \--foreground -Parent process does not exit until its children have finished. It has no effect with -.B \-N -which does not fork/exit at startup. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\--kid roleID" -Play a given SMP kid process role, with a given ID. Do not use -this option. It is meant for the master process use only. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-O options" -Set Windows Service Command line options in Registry. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-r -Remove a Windows Service (see -.B \-n -option). -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-R -Do not set -.B REUSEADDR -on port. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-s -Enable logging to syslog. Also configurable in -.BI @SYSCONFDIR@/squid.conf -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-S -Double-check swap during rebuild. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B "\-u port" -Specify ICP port number (default: 3130), disable with 0. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-v -Print version and build details. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-X -Force full debugging. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-Y -Only return -.B UDP_HIT -or -.B UDP_MISS_NOFETCH -during fast reload. -. -.if !'po4a'hide' .TP -.if !'po4a'hide' .B \-z -Create missing swap directories and other missing cache_dir structures, -then exit. All cache_dir types create the configured top-level directory if -it is missing. Other actions are type-specific. For example, ufs-based -storage systems create missing L1 and L2 directories while Rock creates -the missing database file. -.IP -This option does not enable validation of any present swap structures. Its -focus is on creation of missing pieces. If nothing is missing, squid -z -just exits. If you suspect cache_dir corruption, you must delete the top-level -cache_dir directory before running squid -z. -.IP -By default, squid -z runs in daemon mode (so that configuration macros and -other SMP features work as expected), returning control to the caller -before cache_dirs are fully initialized. If run from init scripts or -daemon managers, the caller often needs to wait for the initialization to -complete before proceeding further. -Use -.B \--foreground -option to prevent premature exits. To disable daemon mode, use -.B \-N -option. -. -.SH FILES -Squid configuration files located in @SYSCONFDIR@/: -. -.if !'po4a'hide' .IP "squid.conf" -The main configuration file. You must initially make changes to this file for -.B squid -to work. For example, the default configuration only allows access from RFC private LAN networks. -Some packaging distributions block even that. -. -.if !'po4a'hide' .IP "squid.conf.default" -Reference copy of the configuration file. Always kept up to date with -the version of Squid you are using. -.IP -Use this to look up the default configuration settings and syntax after upgrading. -. -.if !'po4a'hide' .IP "squid.conf.documented" -Reference copy of the configuration file. Always kept up to date with -the version of Squid you are using. -.IP -Use this to read the documentation for configuration options available in -your build of Squid. The online configuration manual is also available for -a full reference of options. -.BR see http://www.squid-cache.org/Doc/config/ -. -.if !'po4a'hide' .IP "msntauth.conf" -The main configuration file for the Sample MSNT authenticator. -. -.if !'po4a'hide' .IP "errorpage.css" -CSS Stylesheet to control the display of generated error pages. -Use this to set any company branding you need, it will apply to every -language Squid provides error pages for. -.PP -.br -Some files also located elsewhere: -. -.if !'po4a'hide' .IP "@DEFAULT_MIME_TABLE@ (mime_table)" -MIME type mappings for FTP gatewaying -. -.if !'po4a'hide' .IP "@DEFAULT_ERROR_DIR@" -Location of Squid error pages and templates. -. -.SH AUTHOR -Squid was written over many years by a changing team of developers and maintained in turn by -.if !'po4a'hide' .I Duane Wessels -.if !'po4a'hide' .I Henrik Nordstrom -.if !'po4a'hide' .I Amos Jeffries -.PP -With contributions from many others in the Squid community. -see CONTRIBUTORS for a full list of individuals who contributed code. -see CREDITS for a list of major code contributing copyright holders. -. -.SH COPYRIGHT -.PP - * Copyright (C) 1996-2023 The Squid Software Foundation and contributors - * - * Squid software is distributed under GPLv2+ license and includes - * contributions from numerous individuals and organizations. - * Please see the COPYING and CONTRIBUTORS files for details. -. -.SH QUESTIONS -Questions on the usage of this program can be sent to the -.I Squid Users mailing list -.if !'po4a'hide' -. -.SH REPORTING BUGS -Bug reports need to be made in English. -See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report. -.PP -Report bugs or bug fixes using https://bugs.squid-cache.org/ -.PP -Report serious security bugs to -.I Squid Bugs -.PP -Report ideas for new improvements to the -.I Squid Developers mailing list -.if !'po4a'hide' -. -.SH SEE ALSO -.if !'po4a'hide' .B basic_pam_auth "(8), " -.if !'po4a'hide' .B basic_ldap_auth "(8), " -.if !'po4a'hide' .B ext_ldap_group_acl "(8), " -.if !'po4a'hide' .B ext_session_acl "(8), " -.if !'po4a'hide' .B ext_unix_group_acl "(8), " -.br -The Squid FAQ wiki -.if !'po4a'hide' https://wiki.squid-cache.org/SquidFaq -.br -The Squid Configuration Manual -.if !'po4a'hide' http://www.squid-cache.org/Doc/config/ diff --git a/src/squid.md b/src/squid.md new file mode 100644 index 00000000000..3f8ac276482 --- /dev/null +++ b/src/squid.md @@ -0,0 +1,247 @@ +--- +title: squid +section: 8 +--- +# NAME + +**squid** - HTTP web proxy caching server + +# SYNOPSIS + +**squid** [-dsCFNRSXY] [-\-foreground] [-l facility] [-f file] [-[au] port] [-k signal] [-n service] + +**squid** -[hv] + +**squid** -n service -i [-dsX] [-\-foreground] [-l facility] + +**squid** -n service -r [-dsX] [-\-foreground] [-l facility] + +**squid** -n service -O command [-ds] [-\-foreground] [-l facility] + +**squid** -z [-NS] [-dsX] [-\-foreground] [-l facility] [-f file] [-n service] + +# DESCRIPTION + +**squid** is a high-performance proxy caching server for web +clients, supporting FTP, ICAP, ICP, HTCP and HTTP data objects. +Unlike traditional caching software, Squid handles all requests +in a single, non-blocking process. + +Squid keeps meta data and especially hot objects cached in RAM, +caches DNS lookups, supports non-blocking DNS lookups, and +implements negative caching of failed requests. + +Squid supports TLS, extensive access controls, and full request +logging. By using the lightweight Internet Cache Protocols ICP, +HTCP or CARP, Squid caches can be arranged in a hierarchy or +mesh for additional bandwidth savings. + +Squid consists of a main server program **squid**, some optional +programs for custom processing and authentication, and some +management and client tools. When squid starts up, it spawns a +configurable number of helper processes, each of which can +perform parallel lookups. This reduces the amount of time the +cache waits for results. + +Squid is derived from the ARPA funded Harvest Project. + +This manual page only lists the command line arguments. For +details on how to configure Squid see the file +**@SYSCONFDIR@/squid.conf.documented**, the Squid +[wiki FAQ](https://wiki.squid-cache.org/) and examples, or the +[configuration manual](http://www.squid-cache.org/Doc/config/). + +# OPTIONS + +-a port +> Specify HTTP port number where Squid should listen for + requests, in addition to any + [http_port](http://www.squid-cache.org/Doc/config/html_port/) + in **@SYSCONFDIR@/squid.conf** + +-C +> Do not catch fatal signals. + +-d level +> Write debugging to stderr also. + +-f file +> Use the given file instead of @SYSCONFDIR@/squid.conf . + If the file name starts with a **!** or **|** then it is + assumed to be an external command or command line. Can for + example be used to pre\-process the configuration before it is + being read by Squid. To facilitate this Squid also understands + the common #line notion to indicate the real source file. + +-F +> Don't serve any requests until store is rebuilt. + +-h +> Print help message. + +-i +> Install as a Windows Service (see **"-n"** option). + +-k [ reconfigure | rotate | shutdown | interrupt | kill | debug | check | parse ] +> Parse configuration file, then send signal to running copy + (except **"-k parse"**) and exit. + +-l facility +> Use specified syslog facility. Implies **"-s"** + +-n name +> Specify Windows Service name to use for service operations. + The default is **"Squid"** + +-N +> No daemon mode. + +-\-foreground +> Parent process does not exit until its children have finished. + It has no effect with **"-N"** which does not fork/exit at + startup. + +-\-kid roleID +> Play a given SMP kid process role, with a given ID. + **Do not use this option**. It is meant for the master process + use only. + +-O options +> Set Windows Service Command line options in Registry. + +-r +> Remove a Windows Service (see **"-n"** option). + +-R +> Do not set **REUSEADDR** on port. + +-s +> Enable logging to syslog. Also configurable in + **@SYSCONFDIR@/squid.conf** + +-S +> Double-check swap during rebuild. + +-u port +> Specify ICP port number. + +-v +> Print version and build details. + +-X +> Force full debugging. + +-Y +> Only return **UDP_HIT** or **UDP_MISS_NOFETCH** during fast + reload. + +-z +> Create missing swap directories and other missing + [cache_dir](http://www.squid-cache.org/Doc/config/cache_dir/) + structures, then exit. +> All cache_dir types create the configured top-level directory + if it is missing. Other actions are type-specific. +> This option does not enable validation of any present swap + structures. Its focus is on creation of missing pieces. +> If nothing is missing, **squid -z** just exits. +> If you suspect cache_dir corruption, you must delete the + top-level cache_dir directory before running **squid -z**. +> By default, **squid -z** runs in daemon mode so that + configuration macros and other SMP features work as expected, + returning control to the caller before cache_dirs are fully + initialized. +> If run from init scripts or daemon managers, the caller often + needs to wait for the initialization to complete before + proceeding further. +> Use **"-\-foreground"** option to prevent premature exits. +> Use **-N** option to disable daemon mode. + +# FILES + +Squid configuration files located in @SYSCONFDIR@/: + +squid.conf +> The main configuration file. +> You must initially make changes to this file for **squid** to + work. + +squid.conf.default +> Reference copy of the configuration file. Always kept up to + date with the version of Squid you are using. +> Use this to look up the default configuration settings and + syntax after upgrading. + +squid.conf.documented +> Reference copy of the configuration file. Always kept up to + date with the version of Squid you are using. +> Use this to read the documentation for configuration options + available in your build of Squid. +> The [online configuration manual](http://www.squid-cache.org/Doc/config/) + is also available for a full reference of options. + +errorpage.css +> CSS Stylesheet to control display of generated error pages. +> Use this to set any company branding you need, it will apply + to every language Squid provides error pages for. + +Some files also located elsewhere: + +mime_table @DEFAULT_MIME_TABLE@ +> MIME type mappings for FTP gatewaying +> Can be configured with the + [mime_table directive](http://www.squid-cache.org/Doc/config/mime_table/) + +error_directory @DEFAULT_ERROR_DIR@ +> Location of Squid error pages and templates. + +# AUTHOR + +Squid was written over many years by a changing team of +developers and maintained in turn by + *Duane Wessels *, + *Henrik Nordstrom *, + *Amos Jeffries *, + *Francesco Chemolli * + +With contributions from many others in the Squid community. + +See CONTRIBUTORS for a full list of individuals who contributed +code. + +See CREDITS for a list of major code contributing copyright +holders. + +# COPYRIGHT + + * Copyright (C) 1996-2024 The Squid Software Foundation and contributors + * + * Squid software is distributed under GPLv2+ license and includes + * contributions from numerous individuals and organizations. + * Please see the COPYING and CONTRIBUTORS files for details. + +# QUESTIONS + +Questions on the usage of this program can be sent to the +*Squid Users* mailing list . + +# REPORTING BUGS + +Bug reports need to be made in English. +See https://wiki.squid-cache.org/SquidFaq/BugReporting for +details of what you need to include with your bug report. + +Report bugs or bug fixes using https://bugs.squid-cache.org/. + +Report serious security bugs to +*Squid Bugs* mailing list . + +Report ideas for new improvements to the +*Squid Developers* mailing list . + +# SEE ALSO + +The [FAQ wiki](https://wiki.squid-cache.org/SquidFaq) + +The [Configuration Manual](http://www.squid-cache.org/Doc/config/) + +The [Helper Manuals](http://www.squid-cache.org/Doc/man/)