Re: [PATCH] DOC: configuration.txt: add log-balance documentation

[Willy Tarreau]

On Wed, Nov 22, 2023 at 04:13:22PM +0100, Aurelien DARRAGON wrote:
> > Got it, sorry for the noise then.
> 
> No worries, thank you for noticing it!

I missed that one before dev11 but it's merged now. Thank you guys!
willy

Re: [PATCH] DOC: configuration.txt: add log-balance documentation

[Aurelien DARRAGON]

> Got it, sorry for the noise then.

No worries, thank you for noticing it!


Regards,
Aurelien

Re: [PATCH] DOC: configuration.txt: add log-balance documentation

[Marko Juraga]

Hi Aurelien,

On 22. 11. 2023. 15:16, Aurelien DARRAGON wrote:
> Hi Marko,
> 
> Thanks for the heads up,
> 
> In fact "log-balance" directive was removed i>
>> commit b61147fd2a54d4cfc1053a51e87c91cc306bb7ed
>> Author: Aurelien DARRAGON 
>> Date:   Wed Nov 15 11:15:50 2023 +0100
>>
>> MEDIUM: log/balance: merge tcp/http algo with log ones
> 
> log load balancing may now be configured using the existing "balance"
> directive for log backends as explained in the haproxy-2.9-dev10 release
> note.

Got it, sorry for the noise then.

> However I forgot to remove the "log-balance" keyword from the proxy
> keyword matrix, which could explain why you thought the documentation
> was missing. My bad!

That is why I was suspicious that it's missing indeed.

Regards,
Marko

Re: [PATCH] DOC: configuration.txt: add log-balance documentation

[Aurelien DARRAGON]

Hi Marko,

Thanks for the heads up,

In fact "log-balance" directive was removed in

> commit b61147fd2a54d4cfc1053a51e87c91cc306bb7ed
> Author: Aurelien DARRAGON 
> Date:   Wed Nov 15 11:15:50 2023 +0100
> 
> MEDIUM: log/balance: merge tcp/http algo with log ones

log load balancing may now be configured using the existing "balance"
directive for log backends as explained in the haproxy-2.9-dev10 release
note.

However I forgot to remove the "log-balance" keyword from the proxy
keyword matrix, which could explain why you thought the documentation
was missing. My bad!

Here is a complementary patch to
b61147fd2a54d4cfc1053a51e87c91cc306bb7ed to remove the documentation
leftovers for "log-balance" directive which doesn't exist anymore in the
code.

AurelienFrom 8e675f826498c5c6d8067d5a77427ee13423d89b Mon Sep 17 00:00:00 2001
From: Aurelien DARRAGON 
Date: Tue, 21 Nov 2023 11:28:26 +0100
Subject: [PATCH] DOC: config: removing "log-balance" references

"log-balance" keyword was removed by b61147f ("MEDIUM: log/balance: merge
tcp/http algo with log ones") but it was still documented.

Removing "log-balance" references in the documentation where needed.
---
 doc/configuration.txt | 6 ++
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index c2f30a944..414bfdc6f 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -4500,7 +4500,6 @@ id-  X X X
 ignore-persist-  - X X
 load-server-state-from-file   X  - X X
 log  (*)  X  X X X
-log-balance   X  - X X
 log-formatX  X X -
 log-format-sd X  X X -
 log-tag   X  X X X
@@ -9115,10 +9114,9 @@ mode { tcp|http|log }
   any "log" directive by using the "backend@" syntax. Log
   messages will be distributed to the servers from the backend
   according to the lb settings which can be configured using the
-  "log-balance" keyword (in place of the "balance" keyword for TCP
-  and HTTP backends). Log backends support UDP servers by prefixing
+  "balance" keyword. Log backends support UDP servers by prefixing
   the server's address with the "udp@" prefix. Common backend and
-  server features are supported, but not TCP or HTTP related ones.
+  server features are supported, but not TCP or HTTP specific ones.
 
   When doing content switching, it is mandatory that the frontend and the
   backend are in the same mode (generally HTTP), otherwise the configuration
-- 
2.34.1

[PATCH] DOC: configuration.txt: add log-balance documentation

[Marko Juraga]

Hi all,

while working on some dataplaneapi fixes, I noticed that the docs for
the log-balance keyword are missing in configuration.txt so sending a patch.

Regards,
Marko Juraga

From 270225cec77b28195ec6bb2b19db32deeabb6840 Mon Sep 17 00:00:00 2001
From: Marko Juraga 
Date: Wed, 22 Nov 2023 14:57:08 +0100
Subject: [PATCH] DOC: configuration.txt: add log-balance documentation

Adding missing documentation for the newly added log-balance
configuration keyword.
---
 doc/configuration.txt | 75 +++
 1 file changed, 75 insertions(+)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 898fe97c8..6c6aad8c1 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -8973,6 +8973,81 @@ no log
 # level and send in tcp
 log "${LOCAL_SYSLOG}:514" local0 notice   # send to local server
 
+log-balance  [  ]
+  Define the load balancing algorithm to be used in a log backend.
+  ("mode log" enabled)
+
+  May be used in sections :   defaults | frontend | listen | backend
+ yes   |no|   yes  |   yes
+  Arguments :
+ is the algorithm used to select a server when doing load
+balancing. This only applies when no persistence information
+is available, or when a connection is redispatched to another
+server.  may be one of the following :
+
+  roundrobin  Each server is used in turns. This is the smoothest and
+  fairest algorithm when the server's processing time remains
+  equally distributed.
+
+  sticky  The first server in the list of available servers receives all
+  the log messages. When the server goes DOWN, the next server
+  in the list takes its place. When a previously DOWN server
+  goes back UP it is added at the end of the list so that the
+  sticky server doesn't change until it becomes DOWN.
+
+  random  A random number will be used as the key for the server
+  lookup. Random log balancing can be useful with large farms
+  or when servers are frequently added or removed from the
+  pool of available servers as it may avoid the hammering
+  effect that could result from roundrobin in this situation.
+
+  hash should be found in the form: 
+  e.g.: log-balance hash 
+
+  Each log message will be passed to the converter list
+  specified in  (ie: "cnv1,cnv2..."), and it will
+  then be passed to haproxy hashing function according to
+  "hash-type" settings. The resulting hash will be used to
+  select the destination server among the ones declared in the
+  log backend. The goal of this algorithm is to be able to
+  extract a key within the final log message using string
+  converters and then be able to stick to the same server thanks
+  to the hash. Only "map-based" hashes are supported for now.
+
+ is an optional list of arguments which may be needed by some
+algorithms.
+
+  The load balancing algorithm of a log backend is set to roundrobin when
+  no other algorithm has been set. The algorithm may only be set once for each
+  log backend. The above algorithms support the "backup" server option and the
+  "allbackups" proxy option. However server "weight" is not supported and will
+  be ignored.
+
+  Example :
+
+global
+  log backend@mylog-rrb local0 # send all logs to mylog-rrb backend
+  log backend@mylog-hash local0 # send all logs to mylog-hash backend
+
+backend mylog-rrb
+  mode log
+  log-balance roundrobin
+
+  server s1 udp@127.0.0.1:514 # will receive 50% of log messages
+  server s2 udp@127.0.0.1:514
+
+backend mylog-hash
+  mode log
+
+  # extract "METHOD URL PROTO" at the end of the log message,
+  # and let haproxy hash it so that log messages generated from
+  # similar requests get sent to the same syslog server:
+  log-balance hash 'field(-2,\")'
+
+  # server list here
+  server s1 127.0.0.1:514
+  #...
+
 log-format 
   Specifies the log format string to use for traffic logs
   May be used in sections:defaults | frontend | listen | backend
-- 
2.34.1

[PATCH 1/2] CI: add naming convention documentation

[Ilya Shipitsin]

branches "haproxy-" stand for stable branches, otherwise development
---
 .github/matrix.py | 18 +-
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/.github/matrix.py b/.github/matrix.py
index 7f22c43bb..dbf987e93 100755
--- a/.github/matrix.py
+++ b/.github/matrix.py
@@ -21,6 +21,14 @@ else:
 print("Usage: {} ".format(sys.argv[0]), file=sys.stderr)
 sys.exit(1)
 
+#
+# this CI is used for both development and stable branches of HAProxy
+#
+# naming convention used, if branch name matches:
+#
+#   "haproxy-" - stable branches
+#   otherwise  - development branch (i.e. "latest" ssl variants, "latest" 
github images)
+#
 print("Generating matrix for branch '{}'.".format(ref_name))
 
 
@@ -83,9 +91,9 @@ matrix = []
 # Ubuntu
 
 if "haproxy-" in ref_name:
-os = "ubuntu-22.04"
+os = "ubuntu-22.04" # stable branch
 else:
-os = "ubuntu-latest"
+os = "ubuntu-latest" # development branch
 
 TARGET = "linux-glibc"
 for CC in ["gcc", "clang"]:
@@ -179,7 +187,7 @@ for CC in ["gcc", "clang"]:
 # "BORINGSSL=yes",
 ]
 
-if "haproxy-" not in ref_name:
+if "haproxy-" not in ref_name: # development branch
 ssl_versions = ssl_versions + [
 "OPENSSL_VERSION=latest",
 "LIBRESSL_VERSION=latest",
@@ -211,9 +219,9 @@ for CC in ["gcc", "clang"]:
 # macOS
 
 if "haproxy-" in ref_name:
-os = "macos-12"
+os = "macos-12" # stable branch
 else:
-os = "macos-latest"
+os = "macos-latest" # development branch
 
 TARGET = "osx"
 for CC in ["clang"]:
-- 
2.40.1

Re: Is tune.quic.backend.max-idle-timeout missing from the documentation?

[Shawn Heisey]

On 6/28/23 08:17, Nick Ramirez wrote:
The HAProxy source code indicates that there is a directive named 
'tune.quic.backend.max-idle-timeout': haproxy/src/cfgparse-quic.c at 
f473eb72066e02d44837fd77110b6ca5bdea97e2 · haproxy/haproxy (github.com) 
<https://github.com/haproxy/haproxy/blob/f473eb72066e02d44837fd77110b6ca5bdea97e2/src/cfgparse-quic.c#L121>. But I do not find it in the documentation. Is it missing? There is 'tune.quic.frontend.max-idle-timeout'.


Not an expert in this ... but I see in "haproxy -vv" output for HAProxy 
version 2.8.0-8ee9a5-30 2023/06/22 that the QUIC multiplexer only 
applies to frontend, not backend.  Could be that the option was put in 
the code so it's already there when/if QUIC backend support is added.


Thanks,
Shawn

Is tune.quic.backend.max-idle-timeout missing from the documentation?

[Nick Ramirez]

The HAProxy source code indicates that there is a directive named 
'tune.quic.backend.max-idle-timeout': haproxy/src/cfgparse-quic.c at 
f473eb72066e02d44837fd77110b6ca5bdea97e2 · haproxy/haproxy (github.com) 
<https://github.com/haproxy/haproxy/blob/f473eb72066e02d44837fd77110b6ca5bdea97e2/src/cfgparse-quic.c#L121>. 
But I do not find it in the documentation. Is it missing? There is 
'tune.quic.frontend.max-idle-timeout'.


Thank you,
Nick Ramirez

Re: [PATCH] DOC: Improve documentation of the various hdr() fetches

[Christopher Faulet]

Le 23/01/2021 à 17:50, Tim Duesterhus a écrit :

GitHub issue #796 notes that many administrators miss the fact that the `hdr()`
fetch (without the `f`) splits the header value at commas. This is only
mentioned at the end of a long paragraph.

This patch attempts to improve the documentation by:
- Explaning the "comma issue" as early as possible.
- Adding newlines to split the explanation into distinct sections.
- Reducing duplication by making the `res` siblings refer to their `req`
   counterparts.

This patch may be backported as long as it applies cleanly. During the
refactoring I needed to adjust several explanations for consistency and not all
of them might be available in older branches.
---


Merged now, thanks !

--
Christopher Faulet

[PATCH] DOC: Improve documentation of the various hdr() fetches

[Tim Duesterhus]

GitHub issue #796 notes that many administrators miss the fact that the `hdr()`
fetch (without the `f`) splits the header value at commas. This is only
mentioned at the end of a long paragraph.

This patch attempts to improve the documentation by:
- Explaning the "comma issue" as early as possible.
- Adding newlines to split the explanation into distinct sections.
- Reducing duplication by making the `res` siblings refer to their `req`
  counterparts.

This patch may be backported as long as it applies cleanly. During the
refactoring I needed to adjust several explanations for consistency and not all
of them might be available in older branches.
---
 doc/configuration.txt | 210 +++---
 1 file changed, 116 insertions(+), 94 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 899bdf553..4dd105d44 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -18509,33 +18509,44 @@ hdr([[,]]) : string
   unambiguously apply to the request headers.
 
 req.fhdr([,]) : string
-  This extracts the last occurrence of header  in an HTTP request. When
-  used from an ACL, all occurrences are iterated over until a match is found.
+  This returns the full value of the last occurrence of header  in an
+  HTTP request. It differs from req.hdr() in that any commas present in the
+  value are returned and are not used as delimiters. This is sometimes useful
+  with headers such as User-Agent.
+
+  When used from an ACL, all occurrences are iterated over until a match is
+  found.
+
   Optionally, a specific occurrence might be specified as a position number.
   Positive values indicate a position from the first occurrence, with 1 being
   the first one. Negative values indicate positions relative to the last one,
-  with -1 being the last one. It differs from req.hdr() in that any commas
-  present in the value are returned and are not used as delimiters. This is
-  sometimes useful with headers such as User-Agent.
+  with -1 being the last one.
 
 req.fhdr_cnt([]) : integer
   Returns an integer value representing the number of occurrences of request
   header field name , or the total number of header fields if  is
-  not specified. Contrary to its req.hdr_cnt() cousin, this function returns
-  the number of full line headers and does not stop on commas.
+  not specified. Like req.fhdr() it differs from res.hdr_cnt() by not splitting
+  headers at commas.
 
 req.hdr([[,]]) : string
-  This extracts the last occurrence of header  in an HTTP request. When
-  used from an ACL, all occurrences are iterated over until a match is found.
+  This returns the last comma-separated value of the header  in an HTTP
+  request. The fetch considers any comma as a delimiter for distinct values.
+  This is useful if you need to process headers that are defined to be a list
+  of values, such as Accept, or X-Forwarded-For. If full-line headers are
+  desired instead, use req.fhdr(). Please carefully check RFC 7231 to know how
+  certain headers are supposed to be parsed. Also, some of them are case
+  insensitive (e.g. Connection).
+
+  When used from an ACL, all occurrences are iterated over until a match is
+  found.
+
   Optionally, a specific occurrence might be specified as a position number.
   Positive values indicate a position from the first occurrence, with 1 being
   the first one. Negative values indicate positions relative to the last one,
-  with -1 being the last one. A typical use is with the X-Forwarded-For header
-  once converted to IP, associated with an IP stick-table. The function
-  considers any comma as a delimiter for distinct values. If full-line headers
-  are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
-  how certain headers are supposed to be parsed. Also, some of them are case
-  insensitive (e.g. Connection).
+  with -1 being the last one.
+
+  A typical use is with the X-Forwarded-For header once converted to IP,
+  associated with an IP stick-table.
 
   ACL derivatives :
 hdr([[,]]) : exact string match
@@ -18551,34 +18562,36 @@ req.hdr_cnt([]) : integer
 hdr_cnt([]) : integer (deprecated)
   Returns an integer value representing the number of occurrences of request
   header field name , or the total number of header field values if
-   is not specified. It is important to remember that one header line may
-  count as several headers if it has several values. The function considers any
-  comma as a delimiter for distinct values. If full-line headers are desired
-  instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
-  detect presence, absence or abuse of a specific header, as well as to block
-  request smuggling attacks by rejecting requests which contain more than one
-  of certain headers. See "req.hdr" for more information on header matching.
+   is not specified. Like req.hdr() it counts each comma separated
+  part of the header's value. If coun

Re: SSL session cache block size documentation

[William Dauchy]

Hello Valters,

On Wed, Jan 6, 2021 at 4:26 PM Valters Jansons  wrote:
> There is a global parameter for SSL session cache block count
> (tune.ssl.cachesize). Documentation for it currently states: A block
> uses approximately 200 bytes of memory.
> This estimate of 200B for each block has been there since version 1.5,
> and it does not seem to align with what we are seeing on our systems
> where it is a bit below 300B at first glance.
> Could some more details be provided on how the 200 bytes number was
> established?

(ccing who did the last modification on this doc)
I believe this is based on `sizeof(struct sh_ssl_sess_hdr) +
SHSESS_BLOCK_MIN_SIZE` calculation used for `shctx_init` function,
which is still 200 bytes today.

> Could the documentation be updated to include such
> information?

I will send a proposal patch.

> From a configuration perspective - could it be possible to only
> provide the preferred footprint (memory size) instead of providing the
> number of blocks?

I will let Erneric or William L. answer this one.
-- 
William

SSL session cache block size documentation

[Valters Jansons]

Hello everyone,

There is a global parameter for SSL session cache block count
(tune.ssl.cachesize). Documentation for it currently states: A block
uses approximately 200 bytes of memory.

This estimate of 200B for each block has been there since version 1.5,
and it does not seem to align with what we are seeing on our systems
where it is a bit below 300B at first glance.

Could some more details be provided on how the 200 bytes number was
established? Could the documentation be updated to include such
information?

>From a configuration perspective - could it be possible to only
provide the preferred footprint (memory size) instead of providing the
number of blocks?

Re: DOC: Update documentation / comments to be gender neutral

[Willy Tarreau]

On Mon, Jul 27, 2020 at 12:10:02AM +0200, Tim Düsterhus wrote:
> Willy,
> 
> Am 26.07.20 um 22:34 schrieb Willy Tarreau:
> > Just a small point, Jackie, as I noticed you fixed several bad constructs
> > of "he" instead of "it", it's worth noting that in some latin languages
> > (like French or Spanish), a number of common words are arbitrarily male
> > or female. A car is female, a truck is male, a plane is male and a space
> > shuttle is female. I could give plenty of examples like this, as there's
> > almost no equivalent for "it". [...]
> 
> Today I learned. I thought that having gendered nouns was unique to
> German or as Mark Twain said in "The Awful German Language"
> (https://en.wikipedia.org/wiki/The_Awful_German_Language):
(...)

Then I learned as well :-)  Maybe in the end it's only English that has
no gender! English people speaking french are often having difficulties
spotting the right gender, which makes their sentences sound funny but
this doesn't affect comprehension at all since the genders for things do
not come from anything logical.

> > This comforts my beliefs that avoiding mentions of the user in general is
> > by far the best solution, and that when not possible (due to generalizing),
> > it's best to use a plural form (since in this case what is described doesn't
> > apply to a single user but to all of them). In this case instead of writing
> 
> Please note that the "they" is no plural form here. It's a so-called
> "Singular they": https://en.wikipedia.org/wiki/Singular_they

I noticed, but it's definitely not the level of detail that we were
taught in English courses at school. When you have 1-2 hours a week,
there are definitely more important things to put the focus on, and
most of what many of us learned was through participation on mailing
lists.

> In German we don't have an equivalent for that. I don't know about
> French. By now it feels pretty natural to me, though.

We don't have an equivalent either, hence the use of "he" for "it"
sometimes, or "he/she" for a more polite or inclusive form, though
for to designate a person. For "his/her/their" we use the same term
("leur") so that removes the need to think about it at all.

But when you look at the examples in the link above, "They are my child",
I'm pretty sure I would have had a zero if I gave a copy with that to any
of my teachers. That's why I'm saying that using such advanced forms should
definitely be frowned upon especially when the user has so little place in
a project like haproxy where both sides are just HTTP agents, and that for
the rare cases where this would be needed, we could easily generalize to
"users" and avoid any confusion, and not require anyone who barely expresses
themself with 400 words to require such difficult rules. That's only my
point: being inclusive, but to the non-native speakers as well.

Cheers,
Willy

Re: DOC: Update documentation / comments to be gender neutral

[Tim Düsterhus]

Willy,

Am 26.07.20 um 22:34 schrieb Willy Tarreau:
> Just a small point, Jackie, as I noticed you fixed several bad constructs
> of "he" instead of "it", it's worth noting that in some latin languages
> (like French or Spanish), a number of common words are arbitrarily male
> or female. A car is female, a truck is male, a plane is male and a space
> shuttle is female. I could give plenty of examples like this, as there's
> almost no equivalent for "it". [...]

Today I learned. I thought that having gendered nouns was unique to
German or as Mark Twain said in "The Awful German Language"
(https://en.wikipedia.org/wiki/The_Awful_German_Language):

"Every noun has a gender, and there is no sense or system in
distribution; so the gender of each must be learned separately and by
heart. There is no other way. To do this one has to have a memory like a
memorandum-book. In German, a young lady has no sex, while a turnip has.
Think what overwrought reverence that shows for the turnip, and what
callous disrespect for the girl."

And indeed sometimes I accidentally slip in a gendered pronoun when
communicating in English.

> This comforts my beliefs that avoiding mentions of the user in general is
> by far the best solution, and that when not possible (due to generalizing),
> it's best to use a plural form (since in this case what is described doesn't
> apply to a single user but to all of them). In this case instead of writing

Please note that the "they" is no plural form here. It's a so-called
"Singular they": https://en.wikipedia.org/wiki/Singular_they

In German we don't have an equivalent for that. I don't know about
French. By now it feels pretty natural to me, though.

Best regards
Tim Düsterhus

Re: DOC: Update documentation / comments to be gender neutral

[Willy Tarreau]

Hi,

On Sun, Jul 26, 2020 at 07:54:17PM +0200, Tim Düsterhus wrote:
> Jackie,
> 
> Am 26.07.20 um 19:02 schrieb Jackie Tapia:
> > Thanks for the suggestion, Tim.
> > 
> > That commit message sounds good to me.
> > 
> 
> Your patch looks good to me now. I've put Willy into Cc to perform the
> final review and commit the patch.

Thanks Jackie, and thanks for handling this review, Tim.

I've read it (and indeed it's much easier now that the first one) and
overall it looks good to me as well.

Just a small point, Jackie, as I noticed you fixed several bad constructs
of "he" instead of "it", it's worth noting that in some latin languages
(like French or Spanish), a number of common words are arbitrarily male
or female. A car is female, a truck is male, a plane is male and a space
shuttle is female. I could give plenty of examples like this, as there's
almost no equivalent for "it". It gets funny when (ab)using some english
words in our jobs because they automatically get the gender of their local
equivalent. As you noticed, some of these slip from French to English when
docs are written, beause while the exercise of translating what you think
to another language is hard, the exercise of thinking in another one is
even harder, and sometimes reading such things are even not noticed, they
are hard-wired in one's brain. As such I think that adopting an advanced
form of English that's not even taught in schools will be even harder to
follow and understand for most of us non-native users (hence the efforts
of "he/she" that you've noticed at a few places).

This comforts my beliefs that avoiding mentions of the user in general is
by far the best solution, and that when not possible (due to generalizing),
it's best to use a plural form (since in this case what is described doesn't
apply to a single user but to all of them). In this case instead of writing
"upon error on any of the parallel requests sent by a user, he/she will be
notified by an error message" (which admittedly looks ugly), or "upon error
on any of the parallel requests sent by a user, they will be notified by an
error message" (which is now wrong since it parses as the requests being
notified instead of the user, at least to any of us for whom English was
only taught as a second language), we'd rather write this using a repetitive
form like "... the user will be notified", or an alternative one like "Users
whose requests triggering an error will be notified by a response...". This
avoids such advanced and difficult forms that are clearly not mastered by
all those who almost only use english to write documentation.

Overall, while I'm used to say that "I/you/we" should absolutely be avoided
in docs (it's not the place to discuss with the user but to explain rules),
we could probably mention that "I/you/he/she/we" are to be avoided and that
the only pronouns left are "it" for singular and "they" for plural, implying
that users will always be designated using the plural form. This simplifies
everything and will force doc writers to think about simpler sentences that
are less ambiguous, and more importantly that are understandable even by
the many who don't have 10 years of English practice behind them.

Regards,
Willy

Re: DOC: Update documentation / comments to be gender neutral

[Tim Düsterhus]

Jackie,

Am 26.07.20 um 19:02 schrieb Jackie Tapia:
> Thanks for the suggestion, Tim.
> 
> That commit message sounds good to me.
> 

Your patch looks good to me now. I've put Willy into Cc to perform the
final review and commit the patch.

Best regards
Tim Düsterhus

Re: DOC: Update documentation / comments to be gender neutral

[Jackie Tapia]

Thanks for the suggestion, Tim.

That commit message sounds good to me.

On Sun, Jul 26, 2020 at 11:49 AM Tim Düsterhus  wrote:

> Jackie,
>
> Am 26.07.20 um 18:36 schrieb Jackie Tapia:
> > I've attached an updated patch.
> >
> Thank you, the Diff LGTM now (however I did not check whether you missed
> any gendered phrasing).
>
> Unfortunately it appears that you missed by remark regarding the missing
> commit message body.
>
> Please make sure to always use a single line commit title *plus* at
> least a single line commit message body. If the title wraps within the
> generated patch files it is probably too long.
>
> Based off your patch and existing commit message, may I suggest the
> following?
>
> ---
> DOC: Use gender neutral language
>
> This patch updates the documentation files and code comments to avoid
> the use of gender specific phrasing in favor of "they" or "it".
> ---
>
> Best regards
> Tim Düsterhus
>
>

-- 

Jackie Tapia

Platform Software Engineer

Sprout Social

sproutsocial.com



Pronouns
<http://www.the519.org/education-training/training-resources/our-resources/creating-authentic-spaces/gender-specific-and-gender-neutral-pronouns>:
She/Her/Hers


0001-DOC-Use-gender-neutral-language.patch
Description: Binary data

Re: DOC: Update documentation / comments to be gender neutral

[Tim Düsterhus]

Jackie,

Am 26.07.20 um 18:36 schrieb Jackie Tapia:
> I've attached an updated patch.
> 
Thank you, the Diff LGTM now (however I did not check whether you missed
any gendered phrasing).

Unfortunately it appears that you missed by remark regarding the missing
commit message body.

Please make sure to always use a single line commit title *plus* at
least a single line commit message body. If the title wraps within the
generated patch files it is probably too long.

Based off your patch and existing commit message, may I suggest the
following?

---
DOC: Use gender neutral language

This patch updates the documentation files and code comments to avoid
the use of gender specific phrasing in favor of "they" or "it".
---

Best regards
Tim Düsterhus

Re: DOC: Update documentation / comments to be gender neutral

[Jackie Tapia]

I've attached an updated patch.

Thanks!



On Sun, Jul 26, 2020 at 10:58 AM Jackie Tapia 
wrote:

> Thank you for the feedback! I'll make those changes.
>
> On Thu, Jul 23, 2020 at 2:14 AM Tim Düsterhus  wrote:
>
>> Jackie,
>>
>> First: I'm a community contributor, so my review might not necessarily
>> reflect that of the HAProxy project. I'm also not a native English
>> speaker.
>>
>> Regarding your patch I have a few comments:
>>
>> From your PR message:
>>
>> > Also, remove some trailing whitespaces from the files modified for
>> funsies.
>>
>> I disagree with this change. This makes the patch larger than it needs
>> to be and it distracts from the important parts of it. If anything it
>> should become a dedicated patch that is separately committed.
>>
>> Regarding your commit messages:
>>
>> Please have a look at the CONTRIBUTING file you modified. Commit
>> messages need to be prefixed with a "tag" ("DOC:" would probably be
>> appropriate) and also contain a body:
>>
>> >As a rule of thumb, your patch MUST NEVER be made only of a subject
>> line,
>> >it *must* contain a description. Even one or two lines, or indicating
>> >whether a backport is desired or not. It turns out that single-line
>> commits
>> >are so rare in the Git world that they require special manual (hence
>> >painful) handling when they are backported, and at least for this
>> reason
>> >it's important to keep this in mind.
>>
>> (
>> https://github.com/haproxy/haproxy/blob/f1ea47d8960730c79cc71fc634b3d7e5909d5683/CONTRIBUTING#L562-L567
>> )
>>
>> Then to the patch itself:
>>
>> - It must not modify the license files doc/lgpl.txt and doc/gpl.txt,
>> because they are standard license texts:
>> https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
>> - In lua.txt it now reads "They just works carefully". I believe it
>> should be "They just work carefully".
>> - In proxy-protocol.txt it now reads "to hide it's activities". I
>> believe it should be "to hide its activities".
>>
>> Best regards
>> Tim Düsterhus
>>
>
>
> --
>
> Jackie Tapia
>
> Platform Software Engineer
>
> Sprout Social
>
> sproutsocial.com
>
>
>
> Pronouns
> <http://www.the519.org/education-training/training-resources/our-resources/creating-authentic-spaces/gender-specific-and-gender-neutral-pronouns>:
> She/Her/Hers
>


-- 

Jackie Tapia

Platform Software Engineer

Sprout Social

sproutsocial.com



Pronouns
<http://www.the519.org/education-training/training-resources/our-resources/creating-authentic-spaces/gender-specific-and-gender-neutral-pronouns>:
She/Her/Hers


0001-DOC-update-documentation-comments-to-be-gender-neutr.patch
Description: Binary data

Re: DOC: Update documentation / comments to be gender neutral

[Jackie Tapia]

Thank you for the feedback! I'll make those changes.

On Thu, Jul 23, 2020 at 2:14 AM Tim Düsterhus  wrote:

> Jackie,
>
> First: I'm a community contributor, so my review might not necessarily
> reflect that of the HAProxy project. I'm also not a native English speaker.
>
> Regarding your patch I have a few comments:
>
> From your PR message:
>
> > Also, remove some trailing whitespaces from the files modified for
> funsies.
>
> I disagree with this change. This makes the patch larger than it needs
> to be and it distracts from the important parts of it. If anything it
> should become a dedicated patch that is separately committed.
>
> Regarding your commit messages:
>
> Please have a look at the CONTRIBUTING file you modified. Commit
> messages need to be prefixed with a "tag" ("DOC:" would probably be
> appropriate) and also contain a body:
>
> >As a rule of thumb, your patch MUST NEVER be made only of a subject
> line,
> >it *must* contain a description. Even one or two lines, or indicating
> >whether a backport is desired or not. It turns out that single-line
> commits
> >are so rare in the Git world that they require special manual (hence
> >painful) handling when they are backported, and at least for this
> reason
> >it's important to keep this in mind.
>
> (
> https://github.com/haproxy/haproxy/blob/f1ea47d8960730c79cc71fc634b3d7e5909d5683/CONTRIBUTING#L562-L567
> )
>
> Then to the patch itself:
>
> - It must not modify the license files doc/lgpl.txt and doc/gpl.txt,
> because they are standard license texts:
> https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
> - In lua.txt it now reads "They just works carefully". I believe it
> should be "They just work carefully".
> - In proxy-protocol.txt it now reads "to hide it's activities". I
> believe it should be "to hide its activities".
>
> Best regards
> Tim Düsterhus
>


-- 

Jackie Tapia

Platform Software Engineer

Sprout Social

sproutsocial.com



Pronouns
:
She/Her/Hers

Re: DOC: Update documentation / comments to be gender neutral

[Tim Düsterhus]

Jackie,

First: I'm a community contributor, so my review might not necessarily
reflect that of the HAProxy project. I'm also not a native English speaker.

Regarding your patch I have a few comments:

>From your PR message:

> Also, remove some trailing whitespaces from the files modified for funsies.

I disagree with this change. This makes the patch larger than it needs
to be and it distracts from the important parts of it. If anything it
should become a dedicated patch that is separately committed.

Regarding your commit messages:

Please have a look at the CONTRIBUTING file you modified. Commit
messages need to be prefixed with a "tag" ("DOC:" would probably be
appropriate) and also contain a body:

>As a rule of thumb, your patch MUST NEVER be made only of a subject line,
>it *must* contain a description. Even one or two lines, or indicating
>whether a backport is desired or not. It turns out that single-line commits
>are so rare in the Git world that they require special manual (hence
>painful) handling when they are backported, and at least for this reason
>it's important to keep this in mind.

(https://github.com/haproxy/haproxy/blob/f1ea47d8960730c79cc71fc634b3d7e5909d5683/CONTRIBUTING#L562-L567)

Then to the patch itself:

- It must not modify the license files doc/lgpl.txt and doc/gpl.txt,
because they are standard license texts:
https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
- In lua.txt it now reads "They just works carefully". I believe it
should be "They just work carefully".
- In proxy-protocol.txt it now reads "to hide it's activities". I
believe it should be "to hide its activities".

Best regards
Tim Düsterhus

DOC: Update documentation / comments to be gender neutral

[Jackie Tapia]

-- 

Jackie Tapia

Platform Software Engineer

Sprout Social

sproutsocial.com



Pronouns
:
She/Her/Hers


0002-Update-contributing-doc.patch
Description: Binary data


0001-Update-docs-comments-to-be-more-inclusive-of-all-gen.patch
Description: Binary data

Re: Documentation

[Cyril Bonté]

Hi all,

Le 11/07/2020 à 15:37, Lukas Tribus a écrit :

But yes, I'm sure Cyril will publish the 2.3-dev documentation
shortly, then the links on haproxy.org will work.


Indeed, 2.3-dev appeared while I was not available. I just had time to 
update the 2.2 documentation in a hurry.


Now, all versions are available, including the dev branch ;-)

--
Cyril Bonté

Re: Documentation

[Aleksandar Lazic]

On 11.07.20 13:11, Tofflan wrote:

Hello!

Im trying to setup a setup HAProxy on my Pfsense router, the links under 
documentation dont work. example: 
https://cbonte.github.io/haproxy-dconv/2.3/intro.html and 
https://cbonte.github.io/haproxy-dconv/2.3/configuration.html
Is there anyway to read or download them somewhere?


The html version is created from the doc/configuration.txt file,
this file should be on all installed haproxy servers because it
should be part of the haproxy package.


Sincerely Fille


Regards
Aleks

Re: Documentation

[Lukas Tribus]

Hello,

On Sat, 11 Jul 2020 at 13:20, Jonathan Matthews  wrote:
>
> On Sat, 11 Jul 2020 at 12:14, Tofflan  wrote:
>>
>> Hello!
>>
>> Im trying to setup a setup HAProxy on my Pfsense router, the links under 
>> documentation dont work. example: 
>> https://cbonte.github.io/haproxy-dconv/2.3/intro.html and 
>> https://cbonte.github.io/haproxy-dconv/2.3/configuration.html
>> Is there anyway to read or download them somewhere?
>
>
> Hey there,
>
> I’m not sure if someone jumped the gun by updating the site’s doc links to 
> reference the unreleased 2.3 version, but you’ll have better luck changing 
> the “2.3” to either 2.2 or 2.0, depending on the version you’re trying to 
> install :-)

Right, 2.3 is a development tree that you will not use in production
anyway. Use the documentation that matches what you are actually
using, and what you should be using is a stable release.

If you are on a bleeding edge development tree, you should be looking
at the files in the doc/ directory anyway, because that is what is as
recent as the code itself.


But yes, I'm sure Cyril will publish the 2.3-dev documentation
shortly, then the links on haproxy.org will work.


cheers,
lukas

Re: Documentation

[Jonathan Matthews]

On Sat, 11 Jul 2020 at 12:14, Tofflan  wrote:

> Hello!
>
> Im trying to setup a setup HAProxy on my Pfsense router, the links under
> documentation dont work. example:
> https://cbonte.github.io/haproxy-dconv/2.3/intro.html and
> https://cbonte.github.io/haproxy-dconv/2.3/configuration.html
> Is there anyway to read or download them somewhere?
>

Hey there,

I’m not sure if someone jumped the gun by updating the site’s doc links to
reference the unreleased 2.3 version, but you’ll have better luck changing
the “2.3” to either 2.2 or 2.0, depending on the version you’re trying to
install :-)

J

> --
Jonathan Matthews
https://jpluscplusm.com

Documentation

[Tofflan]

Hello!

Im trying to setup a setup HAProxy on my Pfsense router, the links under 
documentation dont work. example: 
https://cbonte.github.io/haproxy-dconv/2.3/intro.html and 
https://cbonte.github.io/haproxy-dconv/2.3/configuration.html
Is there anyway to read or download them somewhere?

Sincerely Fille

Re: [PR] Updating Documentation for Hashing

[Willy Tarreau]

Hi Adam,

On Wed, Apr 15, 2020 at 02:23:10AM +0200, PR Bot wrote:
> Dear list!
> 
> Author: Adam Mills 
> Number of patches: 1
> 
> This is an automated relay of the Github pull request:
>Updating Documentation for Hashing
> 
> Patch title(s): 
>Updating Documentation for Hashing

Thanks, now merged, with minor edits:
  - edited the subject line to comply with CONTRIBUTING
  - I kept the link description at the end unmodified ("mixing functions")
since it's the purpose of the link and the article still speaks about
this.

Willy

[PR] Updating Documentation for Hashing

[PR Bot]

Dear list!

Author: Adam Mills 
Number of patches: 1

This is an automated relay of the Github pull request:
   Updating Documentation for Hashing

Patch title(s): 
   Updating Documentation for Hashing

Link:
   https://github.com/haproxy/haproxy/pull/582

Edit locally:
   wget https://github.com/haproxy/haproxy/pull/582.patch && vi 582.patch

Apply locally:
   curl https://github.com/haproxy/haproxy/pull/582.patch | git am -

Description:
   Bret Mulvey, the author of the article cited in this pulication has
   migrated his work to papa.bretmulvey.com. I was able to view an
   archival version of Bret M.'s original post
   (http://home.comcast.net/~bretm/hash/3.html) and have validated that
   this is the same paper that is originally cited.

Instructions:
   This github pull request will be closed automatically; patch should be
   reviewed on the haproxy mailing list (haproxy@formilux.org). Everyone is
   invited to comment, even the patch's author. Please keep the author and
   list CCed in replies. Please note that in absence of any response this
   pull request will be lost.

Re: [PATCH] 3rd round of documentation typo fixes

[Willy Tarreau]

On Fri, Mar 06, 2020 at 11:25:23PM +0500,  ??? wrote:
> Hello,
> 
> I attached a patch based on documentation spelcheck.

Applied, thanks Ilya!
Willy

[PATCH] 3rd round of documentation typo fixes

[Илья Шипицин]

Hello,

I attached a patch based on documentation spelcheck.

Cheers,
Ilya Shipitcin
From ad38d6c0819df867524338a55ac51b3ed8e510be Mon Sep 17 00:00:00 2001
From: Ilya Shipitsin 
Date: Fri, 6 Mar 2020 23:22:22 +0500
Subject: [PATCH] DOC: assorted typo fixes in the documentation

This is the third round of cleanups in various docs
---
 BRANCHES|  2 +-
 doc/design-thoughts/entities-v2.txt |  2 +-
 doc/design-thoughts/http2.txt   |  4 +--
 doc/internals/buffer-api.txt|  2 +-
 doc/internals/entities-v2.txt   |  2 +-
 doc/internals/entities.txt  | 16 +--
 doc/internals/filters.txt   | 16 +--
 doc/internals/htx-api.txt   | 10 +++
 doc/internals/notes-layers.txt  |  6 ++--
 doc/lua-api/index.rst   | 44 ++---
 doc/lua.txt |  4 +--
 11 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/BRANCHES b/BRANCHES
index 521c0ee1f..6cb275c94 100644
--- a/BRANCHES
+++ b/BRANCHES
@@ -191,7 +191,7 @@ Thus the release cycle from 1.8 to 2.2 should look like this:
  `---+---+---+-+---+---+---+--> 1.8 LTS
 
 In short the non-LTS odd releases can be seen as technological previews of the
-next feature release, and will be terminated much ealier. The plan is to barely
+next feature release, and will be terminated much earlier. The plan is to barely
 let them overlap with the next non-LTS release, allowing advanced users to
 always have the choice between the last two major releases.
 
diff --git a/doc/design-thoughts/entities-v2.txt b/doc/design-thoughts/entities-v2.txt
index 905888e22..91c4fa97e 100644
--- a/doc/design-thoughts/entities-v2.txt
+++ b/doc/design-thoughts/entities-v2.txt
@@ -119,7 +119,7 @@ Identified handshake handlers for incoming connections :
   - HH_ACCEPT_PROXY (waits for PROXY line and parses it)
   - HH_TCP_RULES (processes TCP rules)
   - HH_SSL_HS (starts SSL handshake)
-  - HH_ACCEPT_SESSION (instanciates a session)
+  - HH_ACCEPT_SESSION (instantiates a session)
 
 Identified handshake handlers for outgoing connections :
   - HH_SEND_PROXY (tries to build and send the PROXY line)
diff --git a/doc/design-thoughts/http2.txt b/doc/design-thoughts/http2.txt
index 20a5c54c4..c21ac108a 100644
--- a/doc/design-thoughts/http2.txt
+++ b/doc/design-thoughts/http2.txt
@@ -97,7 +97,7 @@
   before the connection timeout so that an unused connection is verified before
   being killed. Abnormal requests must be dealt with using RST_STREAM.
 
-- ALPN : ALPN must be observed onthe client side, and transmitted to the server
+- ALPN : ALPN must be observed on the client side, and transmitted to the server
   side.
 
 - proxy protocol : proxy protocol makes little to no sense in a multiplexed
@@ -134,7 +134,7 @@
   to H2 behind. This can cause some trouble when passing H2 requests to H1
   proxies, because there's no way to know if the request should contain scheme
   and authority in H1 or not based on the H2 request. Thus a "proxy" option
-  will have to be explicitly mentionned on HTTP/1 server lines. One of the
+  will have to be explicitly mentioned on HTTP/1 server lines. One of the
   problem that it creates is that it's not longer possible to pass H/1 requests
   to H/1 proxies without an explicit configuration. Maybe a table of the
   various combinations is needed.
diff --git a/doc/internals/buffer-api.txt b/doc/internals/buffer-api.txt
index 6d192c19d..14a1ac77f 100644
--- a/doc/internals/buffer-api.txt
+++ b/doc/internals/buffer-api.txt
@@ -630,7 +630,7 @@ but fail.
<--> <-->
 oi
 
-There is this correspondance between old and new fields (some will involve a
+There is this correspondence between old and new fields (some will involve a
 knowledge of a channel when the output byte count is required) :
 
  Old| New
diff --git a/doc/internals/entities-v2.txt b/doc/internals/entities-v2.txt
index 38d633d20..86782c34d 100644
--- a/doc/internals/entities-v2.txt
+++ b/doc/internals/entities-v2.txt
@@ -116,7 +116,7 @@ Identified handshake handlers for incoming connections :
   - HH_ACCEPT_PROXY (waits for PROXY line and parses it)
   - HH_TCP_RULES (processes TCP rules)
   - HH_SSL_HS (starts SSL handshake)
-  - HH_ACCEPT_SESSION (instanciates a session)
+  - HH_ACCEPT_SESSION (instantiates a session)
 
 Identified handshake handlers for outgoing connections :
   - HH_SEND_PROXY (tries to build and send the PROXY line)
diff --git a/doc/internals/entities.txt b/doc/internals/entities.txt
index d384395f1..cdde82e34 100644
--- a/doc/internals/entities.txt
+++ b/doc/internals/entities.txt
@@ -9,7 +9,7 @@ Listener
 
 A listener is the entity which is part of a frontend and which accepts
 connections. There are as many listeners as there are ip:port couples.
-There is at least one listener instanciate

Re: [PATCH] documentation typo fixes

[Willy Tarreau]

On Fri, Mar 06, 2020 at 03:21:57PM +0500,  ??? wrote:
> as for stable branches, I can run spell check for every branch and send
> appropriate PR for every branch.
> 
> would it be better compared to backporting ?

No, it would be a pain as it will conflict with the backporting process.
If you find that *after backports* there are still lots of documentation
issues that do not exist in later versions, you can occasionally propose
a patch, but that should remain rare enough, and you'd need to get
prepared to hear that we'd sometimes rather not take it if it looks too
invasive. In anyway no spelling changes to code parts in maintenance
branches will be accepted (comments etc) as they're not user-visible.

Thanks!
Willy

Re: [PATCH] documentation typo fixes

[Willy Tarreau]

On Fri, Mar 06, 2020 at 03:19:07PM +0500,  ??? wrote:
> that's nice point to fix speling in earlier documentation as well.
> 
> 
> side question, when some version become "unsupported", has its
> documentation also retired in some sense ?
> for example "here should be documentation for 1.2, but it is archived at
> ..." ?

The doc is entirely part of the project so it must be updated with the
project (hence why fixes are backported) but at the same time it doesn't
get any more fixes once the branch it belongs to dies. We do drop support
for old branches when there's almost nobody using them anymore. As you
noticed, usually we poll the list 6 months to 1 year upfront to ask if
someone still wants a given version to stay supported. If nobody cares
about it, it means nobody will read the old doc either thus it makes
sense not to backport old doc fixes.

Willy

Re: [PATCH] documentation typo fixes

[Илья Шипицин]

as for stable branches, I can run spell check for every branch and send
appropriate PR for every branch.

would it be better compared to backporting ?

пт, 6 мар. 2020 г. в 14:50, Willy Tarreau :

> On Fri, Mar 06, 2020 at 01:09:54PM +0500,  ??? wrote:
> > Hello,
> >
> > ongoing typo fixes.
>
> Thanks Ilya. I re-tagged "DOC" so that we don't forget to consider
> it for backporting, eventhough the parts on the makefile can be
> dropped from backports if they cause trouble.
>
> Willy
>

Re: [PATCH] documentation typo fixes

[Илья Шипицин]

пт, 6 мар. 2020 г. в 14:50, Willy Tarreau :

> On Fri, Mar 06, 2020 at 01:09:54PM +0500,  ??? wrote:
> > Hello,
> >
> > ongoing typo fixes.
>
> Thanks Ilya. I re-tagged "DOC" so that we don't forget to consider
> it for backporting, eventhough the parts on the makefile can be
> dropped from backports if they cause trouble.
>

that's nice point to fix speling in earlier documentation as well.


side question, when some version become "unsupported", has its
documentation also retired in some sense ?
for example "here should be documentation for 1.2, but it is archived at
..." ?


>
> Willy
>

Re: [PATCH] documentation typo fixes

[Willy Tarreau]

On Fri, Mar 06, 2020 at 01:09:54PM +0500,  ??? wrote:
> Hello,
> 
> ongoing typo fixes.

Thanks Ilya. I re-tagged "DOC" so that we don't forget to consider
it for backporting, eventhough the parts on the makefile can be
dropped from backports if they cause trouble.

Willy

[PATCH] documentation typo fixes

[Илья Шипицин]

Hello,

ongoing typo fixes.

Cheers,
Ilya Shipitcin
From c3cd13340c961a62a78b2db924aabf594f2508a4 Mon Sep 17 00:00:00 2001
From: Ilya Shipitsin 
Date: Fri, 6 Mar 2020 13:07:38 +0500
Subject: [PATCH] CLEANUP: fix documentation typos

---
 CONTRIBUTING   | 4 ++--
 INSTALL| 6 +++---
 Makefile   | 8 
 doc/SPOE.txt   | 2 +-
 doc/architecture.txt   | 4 ++--
 doc/coding-style.txt   | 4 ++--
 doc/management.txt | 8 
 doc/regression-testing.txt | 2 +-
 8 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/CONTRIBUTING b/CONTRIBUTING
index 201e122d4..638a64603 100644
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -234,7 +234,7 @@ do not think about them anymore after a few patches.
indented code, which only proves that the person has no consideration for
quality and/or has done it in a hurry (probably worse). Please note that most
bugs were found in low-quality code. Reviewers know this and tend to be much
-   more reluctant to accept poorly formated code because by experience they
+   more reluctant to accept poorly formatted code because by experience they
won't trust their author's ability to write correct code. It is also worth
noting that poor quality code is painful to read and may result in nobody
willing to waste their time even reviewing your work.
@@ -990,7 +990,7 @@ How to be sure to irritate everyone
 Among the best ways to quickly lose everyone's respect, there is this small
 selection, which should help you improve the way you work with others, if
 you notice you're already practising some of them:
-  - repeatedly send improperly formated commit messages, with no type or
+  - repeatedly send improperly formatted commit messages, with no type or
 severity, or with no commit message body. These ones require manual
 edition, maintainers will quickly learn to recognize your name.
 
diff --git a/INSTALL b/INSTALL
index fc0976af5..78424ee3c 100644
--- a/INSTALL
+++ b/INSTALL
@@ -128,7 +128,7 @@ options involved.
 HAProxy in its basic form does not depend on anything beyond a working libc.
 However a number of options are enabled by default, or are highly recommended,
 and these options will typically involve some external components or libraries,
-depending on the targetted platform.
+depending on the targeted platform.
 
 Optional dependencies may be split into several categories :
 
@@ -286,7 +286,7 @@ can be downloaded http://libslz.org/ and is even easier to build.
 
 4.7) Lua
 
-Lua is an embedded programming langage supported by HAProxy to provide more
+Lua is an embedded programming language supported by HAProxy to provide more
 advanced scripting capabilities. Only versions 5.3 and above are supported.
 In order to enable Lua support, please specify "USE_LUA=1" on the command line.
 Some systems provide this library under various names to avoid conflicts with
@@ -523,7 +523,7 @@ Building on AIX 7.2 works fine using the "aix72-gcc" TARGET. It adds two
 special CFLAGS to prevent the loading of AIXs xmem.h and var.h. This is done
 by defining the corresponding include-guards _H_XMEM and _H_VAR. Without
 excluding those header-files the build fails because of redefinition errors.
-Futhermore, the atomic library is added to the LDFLAGS to allow for
+Furthermore, the atomic library is added to the LDFLAGS to allow for
 multithreading via USE_THREAD.
 
 You can easily define your own target with the GNU Makefile. Unknown targets
diff --git a/Makefile b/Makefile
index 6c1d3ece1..4c823fa30 100644
--- a/Makefile
+++ b/Makefile
@@ -40,7 +40,7 @@
 #   USE_LUA  : enable Lua support.
 #   USE_FUTEX: enable use of futex on kernel 2.6. Automatic.
 #   USE_ACCEPT4  : enable use of accept4() on linux. Automatic.
-#   USE_MY_ACCEPT4   : use own implemention of accept4() if glibc < 2.10.
+#   USE_MY_ACCEPT4   : use own implementation of accept4() if glibc < 2.10.
 #   USE_PRCTL: enable use of prctl(). Automatic.
 #   USE_ZLIB : enable zlib library support.
 #   USE_SLZ  : enable slz library instead of zlib (pick at most one).
@@ -141,7 +141,7 @@ MANDIR = $(PREFIX)/share/man
 DOCDIR = $(PREFIX)/doc/haproxy
 
  TARGET system
-# Use TARGET= to optimize for a specifc target OS among the
+# Use TARGET= to optimize for a specific target OS among the
 # following list (use the default "generic" if uncertain) :
 #linux-glibc, linux-glibc-legacy, solaris, freebsd, openbsd, netbsd,
 #cygwin, haiku, aix51, aix52, aix72-gcc, osx, generic, custom
@@ -246,7 +246,7 @@ SILENT_DEFINE =
 # It's automatically appended depending on the targets.
 EXTRA =
 
- CPU dependant optimizations
+ CPU dependent optimizations
 # Some CFLAGS are set by default depending on the target CPU. Those flags only
 # feed CPU_CFLAGS, which in turn feed CFLAGS, so it i

Documentation clarification: option redispatch

[Luke Seelenbinder]

Hello list,

I'm working on improving our error rates (the elusive 0 is rather close), and, 
as a result, working on tightening up our HAProxy configuration. Based on some 
testing I'm doing, I realized there's a bit of a documentation hole around the 
exact behavior of `option redispatch`.

In the part I'm currently debugging, I have two servers. One is the main server 
and one is the backup. Does `option redispatch 1` retry on a backup server if 
the request to the main server fails or does it redispatch to the same (main) 
backend server? Ideally a dispatch could operate across normal/backup server 
pools, but based on behavior, I'm rather convinced it does not. My next step is 
to configure the backup server as a normal server, but assign a weight of 0 to 
make it act as a backup and also allow redispatches.

Is anyone able to shed some light on the specifics of this behavior?

Best,
Luke

—
Luke Seelenbinder
Stadia Maps | Founder
stadiamaps.com

Re: Outdated retries documentation

[Julien Pivotto]

On 17 Dec 11:13, Willy Tarreau wrote:
> Hi Julien,
> 
> On Tue, Dec 17, 2019 at 09:16:37AM +0100, Julien Pivotto wrote:
> > Dear list,
> > 
> > https://github.com/haproxy/haproxy/blob/50603267981a002d2593bfe219e5071d66a8ea65/doc/configuration.txt#L7798-L7809
> > 
> > Is the retries documentation up to date, or should it be updated to
> > specify that not only network errors are retried, but everything that
> > falls into the "retry-on" directive?
> 
> It would indeed make sense to update it to reflect the new possibilities.
> 
> Thanks!
> Willy

Thanks for the confirmation.

As the change is substantial I have created
https://github.com/haproxy/haproxy/issues/412
so we don't forget.

-- 
 (o-Julien Pivotto
 //\Open-Source Consultant
 V_/_   Inuits - https://www.inuits.eu


signature.asc
Description: PGP signature

Re: Outdated retries documentation

[Willy Tarreau]

Hi Julien,

On Tue, Dec 17, 2019 at 09:16:37AM +0100, Julien Pivotto wrote:
> Dear list,
> 
> https://github.com/haproxy/haproxy/blob/50603267981a002d2593bfe219e5071d66a8ea65/doc/configuration.txt#L7798-L7809
> 
> Is the retries documentation up to date, or should it be updated to
> specify that not only network errors are retried, but everything that
> falls into the "retry-on" directive?

It would indeed make sense to update it to reflect the new possibilities.

Thanks!
Willy

Outdated retries documentation

[Julien Pivotto]

Dear list,

https://github.com/haproxy/haproxy/blob/50603267981a002d2593bfe219e5071d66a8ea65/doc/configuration.txt#L7798-L7809

Is the retries documentation up to date, or should it be updated to
specify that not only network errors are retried, but everything that
falls into the "retry-on" directive?

Thanks

-- 
 (o-Julien Pivotto
 //\Open-Source Consultant
 V_/_   Inuits - https://www.inuits.eu


signature.asc
Description: PGP signature

[PATCH 1/2] CLEANUP: lua: Clarify documentation in hlua_http_get_headers

[Tim Duesterhus]

This rewords the comments to be a bit more clear in what is happening.
---
 src/hlua.c | 21 -
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/src/hlua.c b/src/hlua.c
index 1c87daae3..2d29d08f0 100644
--- a/src/hlua.c
+++ b/src/hlua.c
@@ -4692,8 +4692,11 @@ static int hlua_http_new(lua_State *L, struct hlua_txn 
*txn)
return 1;
 }
 
-/* This function creates ans returns an array of HTTP headers.
- * This function does not fails. It is used as wrapper with the
+/* This function creates and returns a table indexed by HTTP header
+ * names. The values are arrays containing one entry each time the
+ * header was encountered.
+ *
+ * This function does not fail. It is used as wrapper with the
  * 2 following functions.
  */
 __LJMP static int hlua_http_get_headers(lua_State *L, struct hlua_txn *htxn, 
struct http_msg *msg)
@@ -4726,28 +4729,28 @@ __LJMP static int hlua_http_get_headers(lua_State *L, 
struct hlua_txn *htxn, str
/* Check for existing entry:
 * assume that the table is on the top of the stack, and
 * push the key in the stack, the function lua_gettable()
-* perform the lookup.
+* performs the lookup.
 */
lua_pushlstring(L, n.ptr, n.len);
lua_gettable(L, -2);
 
switch (lua_type(L, -1)) {
case LUA_TNIL:
-   /* Table not found, create it. */
+   /* Header not yet encountered, create array. */
lua_pop(L, 1); /* remove the nil value. */
lua_pushlstring(L, n.ptr, n.len);  /* push the 
header name as key. */
-   lua_newtable(L); /* create and push empty 
table. */
+   lua_newtable(L); /* create and push empty 
array. */
lua_pushlstring(L, v.ptr, v.len); /* push 
header value. */
-   lua_rawseti(L, -2, 0); /* index header value 
(pop it). */
-   lua_rawset(L, -3); /* index new table with 
header name (pop the values). */
+   lua_rawseti(L, -2, 0); /* add header value to 
the newly created array */
+   lua_rawset(L, -3); /* add the array to the 
table indexed by header name. */
break;
 
case LUA_TTABLE:
-   /* Entry found: push the value in the table. */
+   /* Header encountered, add the value to the 
array. */
len = lua_rawlen(L, -1);
lua_pushlstring(L, v.ptr, v.len); /* push 
header value. */
lua_rawseti(L, -2, len+1); /* index header 
value (pop it). */
-   lua_pop(L, 1); /* remove the table (it is 
stored in the main table). */
+   lua_pop(L, 1); /* remove the array (it is 
stored in the main table). */
break;
 
default:
-- 
2.23.0

Re[2]: The case for changing the documentation syntax

[Nick Ramirez]

It sounds like restructuredText and Asciidoc are the top choices. They 
both look capable:


http://hyperpolyglot.org/lightweight-markup

I can, as a next step, post this as an Issue on the Github project and 
it can be triaged and tracked.


For something like this, it might even make sense to create a new branch 
so that multiple people can work on it. In that case, splitting the 
documentation into multiple files would be helpful too. If approved,  an 
empty file for each section of the documentation could be created in 
order to have the skeleton of the project. Having the documentation 
split into multiple files may make maintaining the documentation easier 
in the future too (i.e. someone could change one section without 
conflicting with a person making a change in another section).


How have collaborative efforts like this been done in the past? How 
would multiple people be able to commit changes to this branch?


Other thoughts?


-- Original Message --
From: "Pavlos Parissis" 
To: "Nick Ramirez" 
Sent: 7/3/2019 10:44:11 AM
Subject: Re: The case for changing the documentation syntax


On Δευτέρα, 1 Ιουλίου 2019 5:01:33 Μ.Μ. CEST Nick Ramirez wrote:

 Hello all,




[...snip...]


 The solution I am proposing:

 Rather than using a home-grown, difficult to parse,
 not-consistently-used grammar. We should use a standard. We should use
 reStructuredText: http://docutils.sourceforge.net/rst.html
 

 The reStructuredText syntax gives us the following benefits:

 * It is well documented
 * Tools exist to parse this and convert it to other formats (such as
 HTML)
 * Tools exist that will "error check" the document to ensure that the
 correct syntax is used throughout configuration.txt (which would become
 configuration.rst)
 * Tools such as Jekyll can easily parse reStructuredText and build
 sophisticated, beautiful webpages that feature search functionality,
 table-of-contents, images, graphs, links, etc. We could really start to
 make the documentation shine!
 * We won't have to worry about updating special tools because
 reStructuredText syntax will allow us to reliably parse it forever
 * reStructuredText is still easily human-readable using a terminal,
 plain-text editor, etc.

 I and others are fully willing to make the conversion to
 reStructuredText, too. What do you all think?




+1 from me. asciidoctor is something you should have a look at and consider as 
well.
I know that people don't like markdown, but it is very simple to use and that 
is, sometimes, more
important than standards and etc.

My cents,
Pavlos

Re: The case for changing the documentation syntax

[Aleksandar Lazic]

Hi.

Am 02.07.2019 um 20:29 schrieb Hugues Alary:
> And for comparison's sake, here's Asciidoc renders on github:
> https://github.com/asciidoctor/asciidoctor/blob/master/README.adoc
> 
> Other features of the asciidoc/asciidoctor ecosystem are:
> - Asciidoc is also standardized
> - https://antora.org/ allows you to build 1 documentation website, from 
> multiple
> documentation repositories.
> - asciidoctor is extendable, either by writing an extension in Javascript
> (https://asciidoctor-docs.netlify.com/asciidoctor.js/extend/extensions/register/)
>  or
> in Ruby (https://asciidoctor.org/docs/user-manual/#example-extensions) and it
> supports custom backends
> 
> Though I have no skin in the game. ReStructuredText is great, I'm merely
> presenting other options.

I have used asciidoctor for some projects, my reason to switch to pandoc
markdown was hat the pdf output of asciidoctor isn't very good especially when
you come to footmarks and bibliography.

Even though I don't like reStructuredText I vote for them as I think it fits
more into the haproxy workflows, AFAIK.

Jm2c

Regards
Aleks

> On Tue, Jul 2, 2019 at 9:05 AM Nick Ramirez  <mailto:nrami...@haproxy.com>> wrote:
> 
> I found this page on Github. It uses reStructuredText and demonstrates how
> Github would render various elements out of the box. Of course, it can be
> made more visually appealing with other tools, but it's a free benefit 
> that
> it renders on Github.
> 
> https://gist.github.com/ionelmc/e876b73e2001acd2140f
> 
> 
> -- Original Message --
> From: "Lukas Tribus" mailto:li...@ltri.eu>>
> To: "Nick Ramirez" mailto:nrami...@haproxy.com>>
> Cc: "haproxy@formilux.org <mailto:haproxy@formilux.org>"
> mailto:haproxy@formilux.org>>; "Cyril"
> mailto:cyril.bo...@free.fr>>
> Sent: 7/1/2019 6:49:50 PM
> Subject: Re: The case for changing the documentation syntax
> 
>> Hello Nick,
>>  
>>  
>> On Mon, 1 Jul 2019 at 17:02, Nick Ramirez > <mailto:nrami...@haproxy.com>> wrote:
>>>  
>>> Hello all,
>>>  
>>> I'd like to propose something radical, but that will greatly help us in
>>> terms of documentation. (And documentation is very important when it
>>> comes to people choosing whether to use a piece of software, as I am 
>>> sure
>>> you agree!)
>>>  
>>> First, the problem: Our documentation at
>>> https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is
>>> written using a sort of home-grown syntax that uses various conventions
>>> for indicating sections, keywords, etc.
>>>  
>>> However, parsing this home-grown documentation is difficult. For 
>>> example,
>>> I contribute to the HAProxy Syntax Support for Atom project
>>> (https://github.com/abulimov/atom-language-haproxy). This is a python
>>> program that must parse the HAProxy configuration.txt file and find the
>>> keywords by first finding specific section titles, then looking for 
>>> lines
>>> that don't have spaces in front of them. That's how we find the keywords
>>> in each section. It must be updated when new versions of HAProxy are
>>> released because new sections are added and the section numbers may
>>> change, and some sections are not reliably using the home-grown syntax.
>>> In short, parsing configuration.txt is difficult, error-prone and
>>> requires regular maintenance because its syntax is:
>>>  
>>> * Not a standard
>>> * Not used consistently throughout the document
>>> * Not easily parsed by existing tools (home-grown tools must be created
>>> and maintained)
>>>  
>>> You may wonder, why do we need to parse configuration.txt? The reasons 
>>> are:
>>>  
>>> * A text file without any styling is difficult to read, so we want to 
>>> add
>>> styling (e.g. convert it to HTML with CSS or offer a PDF download)
>>> * We want search functionality of the document and an auto-generated
>>> table of contents
>>> * We want to write haproxy.cfg files and have them displayed in
>>> syntax-highlighted color when using Github Gist or any modern text 
>>> editor
>>> (Atom, VS Code, Sublime Text, etc.). For that, we must currently parse
>>> configur

Re: Re[2]: The case for changing the documentation syntax

[Hugues Alary]

And for comparison's sake, here's Asciidoc renders on github:
https://github.com/asciidoctor/asciidoctor/blob/master/README.adoc

Other features of the asciidoc/asciidoctor ecosystem are:
- Asciidoc is also standardized
- https://antora.org/ allows you to build 1 documentation website, from
multiple documentation repositories.
- asciidoctor is extendable, either by writing an extension in Javascript (
https://asciidoctor-docs.netlify.com/asciidoctor.js/extend/extensions/register/)
or in Ruby (https://asciidoctor.org/docs/user-manual/#example-extensions)
and it supports custom backends

Though I have no skin in the game. ReStructuredText is great, I'm merely
presenting other options.

On Tue, Jul 2, 2019 at 9:05 AM Nick Ramirez  wrote:

> I found this page on Github. It uses reStructuredText and demonstrates how
> Github would render various elements out of the box. Of course, it can be
> made more visually appealing with other tools, but it's a free benefit that
> it renders on Github.
>
> https://gist.github.com/ionelmc/e876b73e2001acd2140f
>
>
> -- Original Message --
> From: "Lukas Tribus" 
> To: "Nick Ramirez" 
> Cc: "haproxy@formilux.org" ; "Cyril" <
> cyril.bo...@free.fr>
> Sent: 7/1/2019 6:49:50 PM
> Subject: Re: The case for changing the documentation syntax
>
> Hello Nick,
>
>
> On Mon, 1 Jul 2019 at 17:02, Nick Ramirez  wrote:
>
>
> Hello all,
>
> I'd like to propose something radical, but that will greatly help us in
> terms of documentation. (And documentation is very important when it comes
> to people choosing whether to use a piece of software, as I am sure you
> agree!)
>
> First, the problem: Our documentation at
> https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is
> written using a sort of home-grown syntax that uses various conventions for
> indicating sections, keywords, etc.
>
> However, parsing this home-grown documentation is difficult. For example,
> I contribute to the HAProxy Syntax Support for Atom project (
> https://github.com/abulimov/atom-language-haproxy). This is a python
> program that must parse the HAProxy configuration.txt file and find the
> keywords by first finding specific section titles, then looking for lines
> that don't have spaces in front of them. That's how we find the keywords in
> each section. It must be updated when new versions of HAProxy are released
> because new sections are added and the section numbers may change, and some
> sections are not reliably using the home-grown syntax. In short, parsing
> configuration.txt is difficult, error-prone and requires regular
> maintenance because its syntax is:
>
> * Not a standard
> * Not used consistently throughout the document
> * Not easily parsed by existing tools (home-grown tools must be created
> and maintained)
>
> You may wonder, why do we need to parse configuration.txt? The reasons are:
>
> * A text file without any styling is difficult to read, so we want to add
> styling (e.g. convert it to HTML with CSS or offer a PDF download)
> * We want search functionality of the document and an auto-generated table
> of contents
> * We want to write haproxy.cfg files and have them displayed in
> syntax-highlighted color when using Github Gist or any modern text editor
> (Atom, VS Code, Sublime Text, etc.). For that, we must currently parse
> configuration.txt to learn the keywords (as in the atom-language-haproxy
> project mentioned). For example, we use Github Gist, with the
> atom-language-haproxy project, to display HAProxy configuration snippets in
> color on the haproxy.com/blog. It would be easier to maintain this if we
> could parse configuration.text more easily.
>
>
>
> Actually since 7 years we do 2 of the 3 things you mention here;
> documentation.txt and others are parsed automatically (in python) and
> generate a verify nice HTML site, searchable and indexed with table of
> contents, etc:
>
> https://www.mail-archive.com/haproxy@formilux.org/msg07040.html
> https://github.com/cbonte/haproxy-dconv
> https://cbonte.github.io/haproxy-dconv/
>
>
> We use this extensively and are able to point people to specific
> sections or keywords of the documentation. When the documentation is
> inconsistent and breaks the tool, we (or more specifically Cyril)
> fixes it. I don't see any 2.0 specific changes in haproxy-dconv, and
> I'm not sure if a structured text would fix all the issues you have
> with the atom project.
>
> I'm not saying we should maintain configuration.txt as it currently
> is, but to me the status-quo does not feel as dire as you suggested.
>
>
> haproxy-dconv also mentions:
>
>
> The pur

Re[2]: The case for changing the documentation syntax

[Nick Ramirez]

I found this page on Github. It uses reStructuredText and demonstrates 
how Github would render various elements out of the box. Of course, it 
can be made more visually appealing with other tools, but it's a free 
benefit that it renders on Github.


https://gist.github.com/ionelmc/e876b73e2001acd2140f


-- Original Message --
From: "Lukas Tribus" 
To: "Nick Ramirez" 
Cc: "haproxy@formilux.org" ; "Cyril" 


Sent: 7/1/2019 6:49:50 PM
Subject: Re: The case for changing the documentation syntax


Hello Nick,


On Mon, 1 Jul 2019 at 17:02, Nick Ramirez  wrote:


 Hello all,

 I'd like to propose something radical, but that will greatly help us in terms 
of documentation. (And documentation is very important when it comes to people 
choosing whether to use a piece of software, as I am sure you agree!)

 First, the problem: Our documentation at 
https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is written 
using a sort of home-grown syntax that uses various conventions for indicating 
sections, keywords, etc.

 However, parsing this home-grown documentation is difficult. For example, I 
contribute to the HAProxy Syntax Support for Atom project 
(https://github.com/abulimov/atom-language-haproxy). This is a python program 
that must parse the HAProxy configuration.txt file and find the keywords by 
first finding specific section titles, then looking for lines that don't have 
spaces in front of them. That's how we find the keywords in each section. It 
must be updated when new versions of HAProxy are released because new sections 
are added and the section numbers may change, and some sections are not 
reliably using the home-grown syntax. In short, parsing configuration.txt is 
difficult, error-prone and requires regular maintenance because its syntax is:

 * Not a standard
 * Not used consistently throughout the document
 * Not easily parsed by existing tools (home-grown tools must be created and 
maintained)

 You may wonder, why do we need to parse configuration.txt? The reasons are:

 * A text file without any styling is difficult to read, so we want to add 
styling (e.g. convert it to HTML with CSS or offer a PDF download)
 * We want search functionality of the document and an auto-generated table of 
contents
 * We want to write haproxy.cfg files and have them displayed in 
syntax-highlighted color when using Github Gist or any modern text editor 
(Atom, VS Code, Sublime Text, etc.). For that, we must currently parse 
configuration.txt to learn the keywords (as in the atom-language-haproxy 
project mentioned). For example, we use Github Gist, with the 
atom-language-haproxy project, to display HAProxy configuration snippets in 
color on the haproxy.com/blog. It would be easier to maintain this if we could 
parse configuration.text more easily.



Actually since 7 years we do 2 of the 3 things you mention here;
documentation.txt and others are parsed automatically (in python) and
generate a verify nice HTML site, searchable and indexed with table of
contents, etc:

https://www.mail-archive.com/haproxy@formilux.org/msg07040.html
https://github.com/cbonte/haproxy-dconv
https://cbonte.github.io/haproxy-dconv/


We use this extensively and are able to point people to specific
sections or keywords of the documentation. When the documentation is
inconsistent and breaks the tool, we (or more specifically Cyril)
fixes it. I don't see any 2.0 specific changes in haproxy-dconv, and
I'm not sure if a structured text would fix all the issues you have
with the atom project.

I'm not saying we should maintain configuration.txt as it currently
is, but to me the status-quo does not feel as dire as you suggested.


haproxy-dconv also mentions:


 The purpose of this project is to ultimately convert the HAProxy documentation 
into a more generic format (example : ReStructuredText) that would allow for an 
easier spreading of various output files (.pdf, .html, .epub, etc).


So it seems like there is common ground. I'm CCing Cyril who has
invested a lot of time for this already.


I think I agree that we would benefit from moving towards a
standardized, structured text.


Regarding markdown vs reStructuredText vs asciidoc, I don't have a lot
of experience with either of those, but if we go down this road I feel
like we should pick a format that is here to stay and is standardized,
and for me, that is reStructuredText. Markdown is probably the worst
possible choice and I know first hand how the lack of standardization
negatively affects it's interoperability (specifically a site had a JS
based preview that looked different than when the server-side code
parsed it after the submission ... so I have a strong negative opinion
about Markdown).

Readthedocs supports reStructuredText (and discourages but supports
markdown), however asciidoc is not supported. Not that we need to use
readthedocs, but it's something to keep in mind.



cheers,
lukas

Re: The case for changing the documentation syntax

[Lukas Tribus]

Hello Nick,


On Mon, 1 Jul 2019 at 17:02, Nick Ramirez  wrote:
>
> Hello all,
>
> I'd like to propose something radical, but that will greatly help us in terms 
> of documentation. (And documentation is very important when it comes to 
> people choosing whether to use a piece of software, as I am sure you agree!)
>
> First, the problem: Our documentation at 
> https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is 
> written using a sort of home-grown syntax that uses various conventions for 
> indicating sections, keywords, etc.
>
> However, parsing this home-grown documentation is difficult. For example, I 
> contribute to the HAProxy Syntax Support for Atom project 
> (https://github.com/abulimov/atom-language-haproxy). This is a python program 
> that must parse the HAProxy configuration.txt file and find the keywords by 
> first finding specific section titles, then looking for lines that don't have 
> spaces in front of them. That's how we find the keywords in each section. It 
> must be updated when new versions of HAProxy are released because new 
> sections are added and the section numbers may change, and some sections are 
> not reliably using the home-grown syntax. In short, parsing configuration.txt 
> is difficult, error-prone and requires regular maintenance because its syntax 
> is:
>
> * Not a standard
> * Not used consistently throughout the document
> * Not easily parsed by existing tools (home-grown tools must be created and 
> maintained)
>
> You may wonder, why do we need to parse configuration.txt? The reasons are:
>
> * A text file without any styling is difficult to read, so we want to add 
> styling (e.g. convert it to HTML with CSS or offer a PDF download)
> * We want search functionality of the document and an auto-generated table of 
> contents
> * We want to write haproxy.cfg files and have them displayed in 
> syntax-highlighted color when using Github Gist or any modern text editor 
> (Atom, VS Code, Sublime Text, etc.). For that, we must currently parse 
> configuration.txt to learn the keywords (as in the atom-language-haproxy 
> project mentioned). For example, we use Github Gist, with the 
> atom-language-haproxy project, to display HAProxy configuration snippets in 
> color on the haproxy.com/blog. It would be easier to maintain this if we 
> could parse configuration.text more easily.


Actually since 7 years we do 2 of the 3 things you mention here;
documentation.txt and others are parsed automatically (in python) and
generate a verify nice HTML site, searchable and indexed with table of
contents, etc:

https://www.mail-archive.com/haproxy@formilux.org/msg07040.html
https://github.com/cbonte/haproxy-dconv
https://cbonte.github.io/haproxy-dconv/


We use this extensively and are able to point people to specific
sections or keywords of the documentation. When the documentation is
inconsistent and breaks the tool, we (or more specifically Cyril)
fixes it. I don't see any 2.0 specific changes in haproxy-dconv, and
I'm not sure if a structured text would fix all the issues you have
with the atom project.

I'm not saying we should maintain configuration.txt as it currently
is, but to me the status-quo does not feel as dire as you suggested.


haproxy-dconv also mentions:

> The purpose of this project is to ultimately convert the HAProxy 
> documentation into a more generic format (example : ReStructuredText) that 
> would allow for an easier spreading of various output files (.pdf, .html, 
> .epub, etc).

So it seems like there is common ground. I'm CCing Cyril who has
invested a lot of time for this already.


I think I agree that we would benefit from moving towards a
standardized, structured text.


Regarding markdown vs reStructuredText vs asciidoc, I don't have a lot
of experience with either of those, but if we go down this road I feel
like we should pick a format that is here to stay and is standardized,
and for me, that is reStructuredText. Markdown is probably the worst
possible choice and I know first hand how the lack of standardization
negatively affects it's interoperability (specifically a site had a JS
based preview that looked different than when the server-side code
parsed it after the submission ... so I have a strong negative opinion
about Markdown).

Readthedocs supports reStructuredText (and discourages but supports
markdown), however asciidoc is not supported. Not that we need to use
readthedocs, but it's something to keep in mind.



cheers,
lukas

Re: Re[2]: The case for changing the documentation syntax

[Hugues Alary]

Adding my 2 cents here: I write documentation a lot and would like to
mention the Asciidoc format, and more specifically asciidoctor (
https://asciidoctor.org/). Asciidoc is a _very_ powerful syntax yet
extremely simple to use.

Here's a link to their cheat sheet to give you a quick idea of the syntax:
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
And a more in depth manual:
https://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor

On Mon, Jul 1, 2019 at 1:51 PM Nick Ramirez  wrote:

> Yes, either reStructuredText or Markdown would be okay. They both have a
> very intuitive syntax, so newcomers would pick it up and become
> productive with it quickly. It is quite easy to learn either one.
>
>
>
> -- Original Message --
> From: "Aleksandar Lazic" 
> To: "Nick Ramirez" ; "haproxy@formilux.org"
> 
> Sent: 7/1/2019 12:05:15 PM
> Subject: Re: The case for changing the documentation syntax
>
> >Hi Nick.
> >
> >Am 01.07.2019 um 17:01 schrieb Nick Ramirez:
> >>  Hello all,
> >>
> >>  I'd like to propose something radical, but that will greatly help us
> in terms of
> >>  documentation. (And documentation is very important when it comes to
> people
> >>  choosing whether to use a piece of software, as I am sure you agree!)
> >
> >Full Ack. This discussion comes up from time to time and I agree with you
> that a
> >more mainstream format would be nice.
> >
> >>  First, the problem: Our documentation
> >>  at
> https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is
> >>  written using a sort of home-grown syntax that uses various
> conventions for
> >>  indicating sections, keywords, etc.
> >>
> >>  However, parsing this home-grown documentation is difficult. For
> example, I
> >>  contribute to the HAProxy Syntax Support for Atom project
> >>  (https://github.com/abulimov/atom-language-haproxy). This is a python
> program
> >>  that must parse the HAProxy configuration.txt file and find the
> keywords by
> >>  first finding specific section titles, then looking for lines that
> don't have
> >>  spaces in front of them. That's how we find the keywords in each
> section. It
> >>  must be updated when new versions of HAProxy are released because new
> sections
> >>  are added and the section numbers may change, and some sections are
> not reliably
> >>  using the home-grown syntax. In short, parsing configuration.txt is
> difficult,
> >>  error-prone and requires regular maintenance because its syntax is:
> >>
> >>  * Not a standard
> >>  * Not used consistently throughout the document
> >>  * Not easily parsed by existing tools (home-grown tools must be
> created and
> >>  maintained)
> >>
> >>  You may wonder, why do we need to parse configuration.txt? The reasons
> are:
> >>
> >>  * A text file without any styling is difficult to read, so we want to
> add
> >>  styling (e.g. convert it to HTML with CSS or offer a PDF download)
> >>  * We want search functionality of the document and an auto-generated
> table of
> >>  contents
> >>  * We want to write haproxy.cfg files and have them displayed in
> >>  syntax-highlighted color when using Github Gist or any modern text
> editor (Atom,
> >>  VS Code, Sublime Text, etc.). For that, we must currently parse
> >>  configuration.txt to learn the keywords (as in the
> atom-language-haproxy project
> >>  mentioned). For example, we use Github Gist, with the
> atom-language-haproxy
> >>  project, to display HAProxy configuration snippets in color on the
> >>  haproxy.com/blog. It would be easier to maintain this if we could
> parse
> >>  configuration.text more easily.
> >>
> >>  The solution I am proposing:
> >>
> >>  Rather than using a home-grown, difficult to parse,
> not-consistently-used
> >>  grammar. We should use a standard. We should use
> >>  reStructuredText: http://docutils.sourceforge.net/rst.html
> >>
> >>  The reStructuredText syntax gives us the following benefits:
> >>
> >>  * It is well documented
> >>  * Tools exist to parse this and convert it to other formats (such as
> HTML)
> >>  * Tools exist that will "error check" the document to ensure that the
> correct
> >>  syntax is used throughout configuration.txt (which would become
> configuration.rst)
> >>  * Tools such as Jekyll can easily parse reStructuredText an

Re[2]: The case for changing the documentation syntax

[Nick Ramirez]

Yes, either reStructuredText or Markdown would be okay. They both have a 
very intuitive syntax, so newcomers would pick it up and become 
productive with it quickly. It is quite easy to learn either one.




-- Original Message --
From: "Aleksandar Lazic" 
To: "Nick Ramirez" ; "haproxy@formilux.org" 


Sent: 7/1/2019 12:05:15 PM
Subject: Re: The case for changing the documentation syntax


Hi Nick.

Am 01.07.2019 um 17:01 schrieb Nick Ramirez:

 Hello all,

 I'd like to propose something radical, but that will greatly help us in terms 
of
 documentation. (And documentation is very important when it comes to people
 choosing whether to use a piece of software, as I am sure you agree!)


Full Ack. This discussion comes up from time to time and I agree with you that a
more mainstream format would be nice.


 First, the problem: Our documentation
 at https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is
 written using a sort of home-grown syntax that uses various conventions for
 indicating sections, keywords, etc.

 However, parsing this home-grown documentation is difficult. For example, I
 contribute to the HAProxy Syntax Support for Atom project
 (https://github.com/abulimov/atom-language-haproxy). This is a python program
 that must parse the HAProxy configuration.txt file and find the keywords by
 first finding specific section titles, then looking for lines that don't have
 spaces in front of them. That's how we find the keywords in each section. It
 must be updated when new versions of HAProxy are released because new sections
 are added and the section numbers may change, and some sections are not 
reliably
 using the home-grown syntax. In short, parsing configuration.txt is difficult,
 error-prone and requires regular maintenance because its syntax is:

 * Not a standard
 * Not used consistently throughout the document
 * Not easily parsed by existing tools (home-grown tools must be created and
 maintained)

 You may wonder, why do we need to parse configuration.txt? The reasons are:

 * A text file without any styling is difficult to read, so we want to add
 styling (e.g. convert it to HTML with CSS or offer a PDF download)
 * We want search functionality of the document and an auto-generated table of
 contents
 * We want to write haproxy.cfg files and have them displayed in
 syntax-highlighted color when using Github Gist or any modern text editor 
(Atom,
 VS Code, Sublime Text, etc.). For that, we must currently parse
 configuration.txt to learn the keywords (as in the atom-language-haproxy 
project
 mentioned). For example, we use Github Gist, with the atom-language-haproxy
 project, to display HAProxy configuration snippets in color on the
 haproxy.com/blog. It would be easier to maintain this if we could parse
 configuration.text more easily.

 The solution I am proposing:

 Rather than using a home-grown, difficult to parse, not-consistently-used
 grammar. We should use a standard. We should use
 reStructuredText: http://docutils.sourceforge.net/rst.html

 The reStructuredText syntax gives us the following benefits:

 * It is well documented
 * Tools exist to parse this and convert it to other formats (such as HTML)
 * Tools exist that will "error check" the document to ensure that the correct
 syntax is used throughout configuration.txt (which would become 
configuration.rst)
 * Tools such as Jekyll can easily parse reStructuredText and build
 sophisticated, beautiful webpages that feature search functionality,
 table-of-contents, images, graphs, links, etc. We could really start to make 
the
 documentation shine!
 * We won't have to worry about updating special tools because reStructuredText
 syntax will allow us to reliably parse it forever
 * reStructuredText is still easily human-readable using a terminal, plain-text
 editor, etc.

 I and others are fully willing to make the conversion to reStructuredText, too.
 What do you all think?


I would prefer Markdown with pandoc as I don't like the rst format, but I'm fine
with what the community and contributes decides.


 Thanks,
 Nick Ramirez


Regards
Aleks

Re: The case for changing the documentation syntax

[Aleksandar Lazic]

Hi Nick.

Am 01.07.2019 um 17:01 schrieb Nick Ramirez:
> Hello all,
> 
> I'd like to propose something radical, but that will greatly help us in terms 
> of
> documentation. (And documentation is very important when it comes to people
> choosing whether to use a piece of software, as I am sure you agree!)

Full Ack. This discussion comes up from time to time and I agree with you that a
more mainstream format would be nice.

> First, the problem: Our documentation
> at https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is
> written using a sort of home-grown syntax that uses various conventions for
> indicating sections, keywords, etc.
> 
> However, parsing this home-grown documentation is difficult. For example, I
> contribute to the HAProxy Syntax Support for Atom project
> (https://github.com/abulimov/atom-language-haproxy). This is a python program
> that must parse the HAProxy configuration.txt file and find the keywords by
> first finding specific section titles, then looking for lines that don't have
> spaces in front of them. That's how we find the keywords in each section. It
> must be updated when new versions of HAProxy are released because new sections
> are added and the section numbers may change, and some sections are not 
> reliably
> using the home-grown syntax. In short, parsing configuration.txt is difficult,
> error-prone and requires regular maintenance because its syntax is:
> 
> * Not a standard
> * Not used consistently throughout the document
> * Not easily parsed by existing tools (home-grown tools must be created and
> maintained)
> 
> You may wonder, why do we need to parse configuration.txt? The reasons are:
> 
> * A text file without any styling is difficult to read, so we want to add
> styling (e.g. convert it to HTML with CSS or offer a PDF download)
> * We want search functionality of the document and an auto-generated table of
> contents
> * We want to write haproxy.cfg files and have them displayed in
> syntax-highlighted color when using Github Gist or any modern text editor 
> (Atom,
> VS Code, Sublime Text, etc.). For that, we must currently parse
> configuration.txt to learn the keywords (as in the atom-language-haproxy 
> project
> mentioned). For example, we use Github Gist, with the atom-language-haproxy
> project, to display HAProxy configuration snippets in color on the
> haproxy.com/blog. It would be easier to maintain this if we could parse
> configuration.text more easily.
> 
> The solution I am proposing:
> 
> Rather than using a home-grown, difficult to parse, not-consistently-used
> grammar. We should use a standard. We should use
> reStructuredText: http://docutils.sourceforge.net/rst.html
>
> The reStructuredText syntax gives us the following benefits:
> 
> * It is well documented
> * Tools exist to parse this and convert it to other formats (such as HTML)
> * Tools exist that will "error check" the document to ensure that the correct
> syntax is used throughout configuration.txt (which would become 
> configuration.rst)
> * Tools such as Jekyll can easily parse reStructuredText and build
> sophisticated, beautiful webpages that feature search functionality,
> table-of-contents, images, graphs, links, etc. We could really start to make 
> the
> documentation shine!
> * We won't have to worry about updating special tools because reStructuredText
> syntax will allow us to reliably parse it forever
> * reStructuredText is still easily human-readable using a terminal, plain-text
> editor, etc.
> 
> I and others are fully willing to make the conversion to reStructuredText, 
> too.
> What do you all think?

I would prefer Markdown with pandoc as I don't like the rst format, but I'm fine
with what the community and contributes decides.

> Thanks,
> Nick Ramirez

Regards
Aleks

The case for changing the documentation syntax

[Nick Ramirez]

Hello all,

I'd like to propose something radical, but that will greatly help us in 
terms of documentation. (And documentation is very important when it 
comes to people choosing whether to use a piece of software, as I am 
sure you agree!)


First, the problem: Our documentation at 
https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is 
written using a sort of home-grown syntax that uses various conventions 
for indicating sections, keywords, etc.


However, parsing this home-grown documentation is difficult. For 
example, I contribute to the HAProxy Syntax Support for Atom project 
(https://github.com/abulimov/atom-language-haproxy). This is a python 
program that must parse the HAProxy configuration.txt file and find the 
keywords by first finding specific section titles, then looking for 
lines that don't have spaces in front of them. That's how we find the 
keywords in each section. It must be updated when new versions of 
HAProxy are released because new sections are added and the section 
numbers may change, and some sections are not reliably using the 
home-grown syntax. In short, parsing configuration.txt is difficult, 
error-prone and requires regular maintenance because its syntax is:


* Not a standard
* Not used consistently throughout the document
* Not easily parsed by existing tools (home-grown tools must be created 
and maintained)


You may wonder, why do we need to parse configuration.txt? The reasons 
are:


* A text file without any styling is difficult to read, so we want to 
add styling (e.g. convert it to HTML with CSS or offer a PDF download)
* We want search functionality of the document and an auto-generated 
table of contents
* We want to write haproxy.cfg files and have them displayed in 
syntax-highlighted color when using Github Gist or any modern text 
editor (Atom, VS Code, Sublime Text, etc.). For that, we must currently 
parse configuration.txt to learn the keywords (as in the 
atom-language-haproxy project mentioned). For example, we use Github 
Gist, with the atom-language-haproxy project, to display HAProxy 
configuration snippets in color on the haproxy.com/blog. It would be 
easier to maintain this if we could parse configuration.text more 
easily.


The solution I am proposing:

Rather than using a home-grown, difficult to parse, 
not-consistently-used grammar. We should use a standard. We should use 
reStructuredText: http://docutils.sourceforge.net/rst.html



The reStructuredText syntax gives us the following benefits:

* It is well documented
* Tools exist to parse this and convert it to other formats (such as 
HTML)
* Tools exist that will "error check" the document to ensure that the 
correct syntax is used throughout configuration.txt (which would become 
configuration.rst)
* Tools such as Jekyll can easily parse reStructuredText and build 
sophisticated, beautiful webpages that feature search functionality, 
table-of-contents, images, graphs, links, etc. We could really start to 
make the documentation shine!
* We won't have to worry about updating special tools because 
reStructuredText syntax will allow us to reliably parse it forever
* reStructuredText is still easily human-readable using a terminal, 
plain-text editor, etc.


I and others are fully willing to make the conversion to 
reStructuredText, too. What do you all think?


Thanks,
Nick Ramirez

Re: [PATCH 1/2] CLEANUP: Remove appsession documentation

[Willy Tarreau]

On Mon, May 06, 2019 at 01:29:20AM +0200, Tim Düsterhus wrote:
> - What about 'resolution_pool_size'? The only thing it does is emitting
> a warning (not a fatal error). I believe it can also be removed from the
> documentation.

Apparently there is no single stable version with this directive, I
think it was added during development and removed later. Thus both
the doc entry and the parsing can be removed.

> - What about 'block' and 'redispatch' and the various *timeouts which
> are deprecated since more than 5 years (with HAProxy 1.5):
> https://github.com/haproxy/haproxy/commit/de9d2d7b86abb0d7110bc3190aca5b26fec6fd64,
> https://github.com/haproxy/haproxy/commit/a3c504c032614ee65af434e41c08ebe46855ebd8
> and
> https://github.com/haproxy/haproxy/commit/ed44649eb78a8ce5efc203f273c7df774defe2af
>   Currently they appear to still be functional. Perhaps they can be made
> non-functional (fatal error) and removed from the documentation.

While I totally agree with this, I want users of 1.9 to experience the
least possible friction when upgrading to 2.0 because 1.9 is not LTS.
However I'm totally OK with removing them from the doc right now and
removing them completely in 2.1. In addition, I wanted to remove all
the req* and rsp* directives for 1.9 but I recalled it too late in the
development cycle. Similarly I'd like to see all these directives emit
a warning now and be removed in 2.1. Their existence causes too much
trouble, they are not evaluated in the same order as the other ones,
and they are totally emulated nowadays (the header block is artificially
rebuilt, passed to them for regex processing, and the result is parsed
again and reinjected into the headers block). Thus I would welcome a
patch adding the warnings and recommendations for alternatives to all
of them. This along with the legacy HTTP code removal are the things
that could deserve opening the -next branch if someone is interested in
starting these cleanups.

BTW, I merged your two other patches.

Thanks,
Willy

Re: [PATCH 1/2] CLEANUP: Remove appsession documentation

[Tim Düsterhus]

Willy,

partly related to these two patches I already sent:

- What about 'resolution_pool_size'? The only thing it does is emitting
a warning (not a fatal error). I believe it can also be removed from the
documentation.
- What about 'block' and 'redispatch' and the various *timeouts which
are deprecated since more than 5 years (with HAProxy 1.5):
https://github.com/haproxy/haproxy/commit/de9d2d7b86abb0d7110bc3190aca5b26fec6fd64,
https://github.com/haproxy/haproxy/commit/a3c504c032614ee65af434e41c08ebe46855ebd8
and
https://github.com/haproxy/haproxy/commit/ed44649eb78a8ce5efc203f273c7df774defe2af
  Currently they appear to still be functional. Perhaps they can be made
non-functional (fatal error) and removed from the documentation.

Best regards
Tim Düsterhus

[PATCH 1/2] CLEANUP: Remove appsession documentation

[Tim Duesterhus]

I was about to partly revert 294d0f08b3d100fcae0e71c26d4f9f93d26e3569,
because there were no 'X' for 'appsession' in the keyword matrix until
I checked the blame, realizing that the feature does not exist any more.

Clearly the documentation is confusing here, the removal note is only
listed *below* the old documentation and the supported sections still
show 'backend' and 'listen'.

It's been 3.5 years and 4 releases (1.6, 1.7, 1.8 and 1.9), I guess
this can be removed from the documentation of future versions.
---
 doc/configuration.txt | 54 ---
 src/cfgparse-listen.c |  2 +-
 2 files changed, 1 insertion(+), 55 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index ee6f81c1d..80c32863d 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -2221,7 +2221,6 @@ specified in a previous "defaults" section.
  keyword  defaults   frontend   listenbackend
 +--+--+-+-
 acl   -  X X X
-appsession-  - - -
 backlog   X  X X -
 balance   X  - X X
 bind  -  X X -
@@ -2434,59 +2433,6 @@ acl   [flags] [operator]  ...
   See section 7 about ACL usage.
 
 
-appsession  len  timeout 
-   [request-learn] [prefix] [mode ]
-  Define session stickiness on an existing application cookie.
-  May be used in sections :   defaults | frontend | listen | backend
- no|no|   yes  |   yes
-  Arguments :
-   this is the name of the cookie used by the application and which
-   HAProxy will have to learn for each new session.
-
-   this is the max number of characters that will be memorized and
-   checked in each cookie value.
-
- this is the time after which the cookie will be removed from
-   memory if unused. If no unit is specified, this time is in
-   milliseconds.
-
-request-learn
-   If this option is specified, then haproxy will be able to learn
-   the cookie found in the request in case the server does not
-   specify any in response. This is typically what happens with
-   PHPSESSID cookies, or when haproxy's session expires before
-   the application's session and the correct server is selected.
-   It is recommended to specify this option to improve reliability.
-
-prefix When this option is specified, haproxy will match on the cookie
-   prefix (or URL parameter prefix). The appsession value is the
-   data following this prefix.
-
-   Example :
-   appsession ASPSESSIONID len 64 timeout 3h prefix
-
-   This will match the cookie ASPSESSIONIDXXX=,
-   the appsession value will be XXX=.
-
-mode   This option allows to change the URL parser mode.
-   2 modes are currently supported :
-   - path-parameters :
- The parser looks for the appsession in the path parameters
- part (each parameter is separated by a semi-colon), which is
- convenient for JSESSIONID for example.
- This is the default mode if the option is not set.
-   - query-string :
- In this mode, the parser will look for the appsession in the
- query string.
-
-  As of version 1.6, appsessions was removed. It is more flexible and more
-  convenient to use stick-tables instead, and stick-tables support multi-master
-  replication and data conservation across reloads, which appsessions did not.
-
-  See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
- "ignore-persist", "nbproc" and "bind-process".
-
-
 backlog 
   Give hints to the system about the approximate listen backlog desired size
   May be used in sections :   defaults | frontend | listen | backend
diff --git a/src/cfgparse-listen.c b/src/cfgparse-listen.c
index 7c64be102..e7cd0663e 100644
--- a/src/cfgparse-listen.c
+++ b/src/cfgparse-listen.c
@@ -1290,7 +1290,7 @@ int cfg_parse_listen(const char *file, int linenum, char 
**args, int kwm)
}
}
else if (!strcmp(args[0], "appsession")) {  /* cookie name */
-   ha_alert("parsing [%s:%d] : '%s' is not supported anymore, 
please check the documentation.\n", file, linenum, args[0]);
+   ha_alert("parsing [%s:%d] : '%s' is not supported anymore since 
HAProxy 1.6.\n", file, linenum, args[0]);
err_code |= ERR_ALERT | ERR_FATAL;
goto out;
}
-- 
2.21.0

Re: [PATCH] DOC: Add HTX part in the documentation

[Aleksandar Lazic]

Sorry have forgotten to add.

Need to backport to 1.9

Regards
Aleks


 Ursprüngliche Nachricht 
Von: Aleksandar Lazic 
Gesendet: 2. Februar 2019 10:01:26 MEZ
An: haproxy@formilux.org
Betreff: [PATCH] DOC: Add HTX part in the documentation

Hi.

attached a doc update for the new features of HAProxy 1.9.

I hope the patch full fills the CONTRIBUTING rules as
I haven't send patched to the list for long time ;-)

Regards
Aleks

[PATCH] DOC: Add HTX part in the documentation

[Aleksandar Lazic]

Hi.

attached a doc update for the new features of HAProxy 1.9.

I hope the patch full fills the CONTRIBUTING rules as
I haven't send patched to the list for long time ;-)

Regards
AleksFrom c0e025e81b87a23f679aff80bddc02a96c4d43b0 Mon Sep 17 00:00:00 2001
From: Aleksandar Lazic 
Date: Sat, 2 Feb 2019 09:54:55 +0100
Subject: [PATCH] DOC: Add HTX part in the documentation

---
 doc/configuration.txt | 50 +--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index fe5eb250..38ed12ed 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -192,8 +192,7 @@ HAProxy supports 4 connection modes :
 For HTTP/2, the connection mode resembles more the "server close" mode : given
 the independence of all streams, there is currently no place to hook the idle
 server connection after a response, so it is closed after the response. HTTP/2
-is only supported for incoming connections, not on connections going to
-servers.
+supports now end 2 end mode and trailers which is requierd for gRPC.
 
 
 1.2. HTTP request
@@ -384,6 +383,53 @@ Response headers work exactly like request headers, and as such, HAProxy uses
 the same parsing function for both. Please refer to paragraph 1.2.2 for more
 details.
 
+1.3.3. HAProxy HTX
+--
+In this version of HAProxy was a new http-engine developed. With this huge 
+rewrite of the http engine is it now possible to add "easier" some other and 
+new protocols.
+
+It is requierd to use option http-use-htx to activate this new engine.
+
+With HTX is it now possible to handle the following protocols with HAProxy.
+
+TCP <> HTTP/X
+SSL/TLS <> TCP
+SSL/TLS <> HTTP/X
+HTTP/1.x <> HTTP/2
+HTTP/2 <> HTTP/1.x
+
+The Diagramm below was described in this post.
+https://www.mail-archive.com/haproxy@formilux.org/msg31727.html
+
+
+   +-+ stream
+   | all HTTP processing | layer
+   +-+
+   ^ ^ ^
+   HTX | HTX | HTX | normalised
+   v v v  interface
+   +--+ ++ ++ 
+   |applet| | HTTP/1 | | HTTP/2 | whatever layer (called mux for now
+   +--+ ++ ++ but may change once we have others,
+cache || || could be presentation in OSI)
+stats | +--+  | 
+Lua svc   | |TLS   |  | transport layer
+  | +--+  |
+  |   |   | 
++-+ 
+| TCP/Unix/socketpair | control layer
++-+ 
+  |   
++--+
+|file descriptor   |  socket layer
++--+
+  |
+ +---+
+ | operating |
+ |  system   |
+ +---+
+
 
 2. Configuring HAProxy
 --
-- 
2.20.1

[PATCH 12/12] DOC: peers: SSL/TLS documentation for "peers"

[flecaille]

From: Frédéric Lécaille 

---
 doc/configuration.txt | 40 +++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 888515fb..960f1948 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -1928,15 +1928,34 @@ peers 
   Creates a new peer list with name . It is an independent section,
   which is referenced by one or more stick-tables.
 
+bind []: [, ...] [param*]
+  Defines the binding parameters of the local peer of this "peers" section.
+  Such lines are not supported with "peer" line in the same "peers" section.
+
 disabled
   Disables a peers section. It disables both listening and any synchronization
   related to this section. This is provided to disable synchronization of stick
   tables without having to comment out all "peers" references.
 
+default-bind [param*]
+  Defines the binding parameters for the local peer, excepted its address.
+
+default-server [param*]
+  Change default options for a server in a "peers" section.
+
+  Arguments:
+  is a list of parameters for this server. The "default-server"
+  keyword accepts an important number of options and has a complete
+  section dedicated to it. Please refer to section 5 for more
+  details.
+
+
+  See also: "server" and section 5 about server options
+
 enable
   This re-enables a disabled peers section which was previously disabled.
 
-peer  :
+peer  : [param*]
   Defines a peer inside a peers section.
   If  is set to the local peer name (by default hostname, or forced
   using "-L" command line option), haproxy will listen for incoming remote peer
@@ -1955,7 +1974,20 @@ peer  :
   You may want to reference some environment variables in the address
   parameter, see section 2.3 about environment variables.
 
+  Note: "peer" keyword may transparently be replaced by "server" keyword (see
+  "server" keyword explanation below).
+
+server  [:] [param*]
+  As previously mentionned, "peer" keyword may be replaced by "server" keyword
+  with a support for all "server" parameters found in 5.2 paragraph.
+  If the underlying peer is local, : parameters must not be present.
+  These parameters must  be provided on a "bind" line (see "bind" keyword
+  of this "peers" section).
+  Some of these parameters are irrelevant for "peers" sections.
+
+
   Example:
+# The old way.
 peers mypeers
 peer haproxy1 192.168.0.1:1024
 peer haproxy2 192.168.0.2:1024
@@ -1970,6 +2002,12 @@ peer  :
 server srv1 192.168.0.30:80
 server srv2 192.168.0.31:80
 
+   Example:
+ peers mypeers
+ bind 127.0.0.11:10001 ssl crt mycerts/pem
+ default-server ssl verify none
+ server hostA  127.0.0.10:1
+ server hostB  #local peer
 
 3.6. Mailers
 
-- 
2.11.0

Re: [PATCH 10/10] DOC: peers: SSL/TLS documentation for "peers"

[Frederic Lecaille]

On 1/14/19 2:56 PM, Willy Tarreau wrote:

Hi Fred,

first, thanks for reviving this!

On Fri, Jan 11, 2019 at 02:52:24PM +0100, flecai...@haproxy.com wrote:

+bind [param*]
+  Defines the binding parameters of the local peer of this "peers" section.
+  To avoid some redundancy, and as the  and  parameters
+  are already provided on "peer" (or "server") lines, they are not supported
+  by "bind" keyword in "peers" sections.
+

(...)

+   Example:
+ peers mypeers
+ bind ssl crt mycerts/pem
+ default-server ssl verify none
+ server hostA  127.0.0.10:1
+ server hostB  127.0.0.11:10001


Just thinking loud, I find this a bit confusing : "bind" usually is
followed by an address to bind to. And it's even wider than just the
haproxy culture. Here from what I'm seeing you're using it exactly
like "default-server", i.e. you can pass all default settings but not
the address. Thus I think that having a "default-bind" directive would
remove this confusion.


+  Note: "peer" keyword may transparently be replaced by "server" keyword (see
+  "server" keyword explanation below).
+
+server  : [param*]
+  As previously mentionned, "peer" keyword may be replaced by "server" keyword
+  with a support for all "server" parameters found in 5.2 paragraph.
+  Some of these parameters are irrelevant for "peers" sections.


Same here, if "server" also creates a listening address, it's quite
confusing in my opinion.


Yes, this is because the "peers" configuration are supposed to be
duplicated without on each haproxy peer. I agree that
"server" should only means "remote peer". It is confusing for the local
peer. Peers are remote or local, contrary to servers which are only
remote peers.


And this makes me think a bit further. I remember some old discussions
where we were saying that the main problem posed by peers is that they
are forcibly symmetrical ; you cannot use them on a dynamic IP address
or on a set of IP addresses for example because you are not allowed to
put 0.0.0.0 here as it also serves as a destination address. You cannot
use a unix socket nor 127.0.0.1 either, just like it's not possible to
listen both to IPv4 and IPv6 addresses.


yes, the peers section configurations are identical on each peer 
belonging to the section.



And I think that your "bind" + "server" options could solve this in a
very elegant way : what about having "bind" always set the listening
address and "server" always set only the target address ? In this case
we could simply handle the migration by making it an error to have both
"bind" and "peer". And thinking about it, I feel like that's a discussion
we already had in the past.


Ok.


Thus I think we could end up with this :

First step :
   - "peer" does what it currently does, i.e. set both the bind and the
  target address ;
   - "default-server" applies to the server part of the peers
   - "default-bind" applies to the bind part of the peers
   => that's what you did modulo the last option's naming

Then we add this :
   - "bind" only sets the bind address and bind options ;
   - "server" only sets target addresses and server options ;

And this will also solve the problem of testing peers with vtest, since
this time they will work *exactly* like real bind+servers with their own
addresses :-)

What do you think ?


I think that all this makes sense as always ;)
I will send a new series of patches for these modifications asap.

Re: [PATCH 10/10] DOC: peers: SSL/TLS documentation for "peers"

[Willy Tarreau]

Hi Fred,

first, thanks for reviving this!

On Fri, Jan 11, 2019 at 02:52:24PM +0100, flecai...@haproxy.com wrote:
> +bind [param*]
> +  Defines the binding parameters of the local peer of this "peers" section.
> +  To avoid some redundancy, and as the  and  parameters
> +  are already provided on "peer" (or "server") lines, they are not supported
> +  by "bind" keyword in "peers" sections.
> +
(...)
> +   Example:
> + peers mypeers
> + bind ssl crt mycerts/pem
> + default-server ssl verify none
> + server hostA  127.0.0.10:1
> + server hostB  127.0.0.11:10001

Just thinking loud, I find this a bit confusing : "bind" usually is
followed by an address to bind to. And it's even wider than just the
haproxy culture. Here from what I'm seeing you're using it exactly
like "default-server", i.e. you can pass all default settings but not
the address. Thus I think that having a "default-bind" directive would
remove this confusion.

> +  Note: "peer" keyword may transparently be replaced by "server" keyword (see
> +  "server" keyword explanation below).
> +
> +server  : [param*]
> +  As previously mentionned, "peer" keyword may be replaced by "server" 
> keyword
> +  with a support for all "server" parameters found in 5.2 paragraph.
> +  Some of these parameters are irrelevant for "peers" sections.

Same here, if "server" also creates a listening address, it's quite
confusing in my opinion.

And this makes me think a bit further. I remember some old discussions
where we were saying that the main problem posed by peers is that they
are forcibly symmetrical ; you cannot use them on a dynamic IP address
or on a set of IP addresses for example because you are not allowed to
put 0.0.0.0 here as it also serves as a destination address. You cannot
use a unix socket nor 127.0.0.1 either, just like it's not possible to
listen both to IPv4 and IPv6 addresses.

And I think that your "bind" + "server" options could solve this in a
very elegant way : what about having "bind" always set the listening
address and "server" always set only the target address ? In this case
we could simply handle the migration by making it an error to have both
"bind" and "peer". And thinking about it, I feel like that's a discussion
we already had in the past.

Thus I think we could end up with this :

First step :
  - "peer" does what it currently does, i.e. set both the bind and the
 target address ;
  - "default-server" applies to the server part of the peers
  - "default-bind" applies to the bind part of the peers
  => that's what you did modulo the last option's naming

Then we add this :
  - "bind" only sets the bind address and bind options ;
  - "server" only sets target addresses and server options ;

And this will also solve the problem of testing peers with vtest, since
this time they will work *exactly* like real bind+servers with their own
addresses :-)

What do you think ?

Thanks,
Willy

[PATCH 10/10] DOC: peers: SSL/TLS documentation for "peers"

[flecaille]

From: Frédéric Lécaille 

---
 doc/configuration.txt | 23 ++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 888515fb..d55e4bd3 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -1928,6 +1928,12 @@ peers 
   Creates a new peer list with name . It is an independent section,
   which is referenced by one or more stick-tables.
 
+bind [param*]
+  Defines the binding parameters of the local peer of this "peers" section.
+  To avoid some redundancy, and as the  and  parameters
+  are already provided on "peer" (or "server") lines, they are not supported
+  by "bind" keyword in "peers" sections.
+
 disabled
   Disables a peers section. It disables both listening and any synchronization
   related to this section. This is provided to disable synchronization of stick
@@ -1936,7 +1942,7 @@ disabled
 enable
   This re-enables a disabled peers section which was previously disabled.
 
-peer  :
+peer  : [param*]
   Defines a peer inside a peers section.
   If  is set to the local peer name (by default hostname, or forced
   using "-L" command line option), haproxy will listen for incoming remote peer
@@ -1955,6 +1961,15 @@ peer  :
   You may want to reference some environment variables in the address
   parameter, see section 2.3 about environment variables.
 
+  Note: "peer" keyword may transparently be replaced by "server" keyword (see
+  "server" keyword explanation below).
+
+server  : [param*]
+  As previously mentionned, "peer" keyword may be replaced by "server" keyword
+  with a support for all "server" parameters found in 5.2 paragraph.
+  Some of these parameters are irrelevant for "peers" sections.
+
+
   Example:
 peers mypeers
 peer haproxy1 192.168.0.1:1024
@@ -1970,6 +1985,12 @@ peer  :
 server srv1 192.168.0.30:80
 server srv2 192.168.0.31:80
 
+   Example:
+ peers mypeers
+ bind ssl crt mycerts/pem
+ default-server ssl verify none
+ server hostA  127.0.0.10:1
+ server hostB  127.0.0.11:10001
 
 3.6. Mailers
 
-- 
2.11.0

[PATCH] DOC: Fix typos in different subsections of the documentation

[Joseph Herlant]

Hi guys,

Fix typos found in the design-thoughts, internals and lua-api
subsections of the documentation.

Note: I split the whole documentation typos patch in 2 to make it more
readable but those can be merged if preferred of course.

The patch is attached, but if you want to view the diff online, you
can check: 
https://github.com/haproxy/haproxy/compare/master...aerostitch:doc_typos2

Thanks for your help,
Joseph
From 07cc22e6ddbcce966833aba418cdfef9f69b0e2c Mon Sep 17 00:00:00 2001
From: Joseph Herlant 
Date: Tue, 13 Nov 2018 19:45:17 -0800
Subject: [PATCH] DOC: Fix typos in different subsections of the documentation

Fix typos found in the design-thoughts, internals and lua-api
subsections of the documentation.
---
 doc/design-thoughts/connection-reuse.txt | 2 +-
 doc/design-thoughts/entities-v2.txt  | 2 +-
 doc/design-thoughts/http2.txt| 4 ++--
 doc/design-thoughts/rate-shaping.txt | 2 +-
 doc/internals/body-parsing.txt   | 4 ++--
 doc/internals/connection-header.txt  | 2 +-
 doc/internals/entities-v2.txt| 2 +-
 doc/internals/entities.txt   | 2 +-
 doc/internals/filters.txt| 6 +++---
 doc/internals/notes-layers.txt   | 6 +++---
 doc/lua-api/index.rst| 2 +-
 11 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/doc/design-thoughts/connection-reuse.txt b/doc/design-thoughts/connection-reuse.txt
index 2b92836a..4eb22f6c 100644
--- a/doc/design-thoughts/connection-reuse.txt
+++ b/doc/design-thoughts/connection-reuse.txt
@@ -202,7 +202,7 @@ The problem analysed below was solved on 2013/10/22
 |   least with some transport not de-initialized. We might thus need
 |   conn_xprt_close() when conn_xprt_init() fails.
 | 
-| The fd should be conditionned by ->ctrl only, and the transport layer by ->xprt.
+| The fd should be conditioned by ->ctrl only, and the transport layer by ->xprt.
 | 
 | - conn_prepare_ctrl(conn, ctrl) 
 | - conn_prepare_xprt(conn, xprt) 
diff --git a/doc/design-thoughts/entities-v2.txt b/doc/design-thoughts/entities-v2.txt
index 8c9eb484..905888e2 100644
--- a/doc/design-thoughts/entities-v2.txt
+++ b/doc/design-thoughts/entities-v2.txt
@@ -61,7 +61,7 @@ On the accept() side, we probably need to know :
   - if a data-layer accept() has been performed
 => possibly 2 bits, to indicate the need to free()
 
-On the connect() side, we need to konw :
+On the connect() side, we need to know :
   - the desire to send a header (eg: send-proxy)
   - if this header has been sent
 => maybe both info might be combined
diff --git a/doc/design-thoughts/http2.txt b/doc/design-thoughts/http2.txt
index eadaaebe..20a5c54c 100644
--- a/doc/design-thoughts/http2.txt
+++ b/doc/design-thoughts/http2.txt
@@ -117,7 +117,7 @@
   frame size minimum. That means slightly more than 16kB of buffer in each
   direction to process any frame. It will definitely have an impact on the
   deployed maxconn setting in places using less than this (4..8kB are common).
-  Also, the header list is persistant per connection, so if we reach the same
+  Also, the header list is persistent per connection, so if we reach the same
   size as the request, that's another 16kB in each direction, resulting in
   about 48kB of memory where 8 were previously used. A more careful encoder
   can work with a much smaller set even if that implies evicting entries
@@ -216,7 +216,7 @@ have dynamic buffer allocation.
 
 Thus :
 - Tx buffers do not exist. We allocate a buffer on the fly when we're ready to
-  send something that we need to build and that needs to be persistant in case
+  send something that we need to build and that needs to be persistent in case
   of partial send. H1 headers are built on the fly from the header table to a
   temporary buffer that is immediately sent and whose amount of sent bytes is
   the only information kept (like for PROXY protocol). H2 headers are more
diff --git a/doc/design-thoughts/rate-shaping.txt b/doc/design-thoughts/rate-shaping.txt
index 255ae4a7..ca094083 100644
--- a/doc/design-thoughts/rate-shaping.txt
+++ b/doc/design-thoughts/rate-shaping.txt
@@ -63,7 +63,7 @@ This brings us to a very flexible architecture :
- 1 list of rule-based checkpoints per backend
- 1 list of rule-based checkpoints per server
 
-Each of these lists have a lot of rules conditionned by ACLs, just like the
+Each of these lists have a lot of rules conditioned by ACLs, just like the
 use-backend rules, except that all rules are evaluated in turn.
 
 Since we might sometimes just want to enable that without setting any limit and
diff --git a/doc/internals/body-parsing.txt b/doc/internals/body-parsing.txt
index 45d7034b..be209af6 100644
--- a/doc/internals/body-parsing.txt
+++ b/doc/internals/body-parsing.txt
@@ -81,7 +81,7 @@ msg.sov  : start of value. First character of the header's value in the header
 
 msg.sol  : start of line. Points to the beg

[PATCH] DOC: fix a few typos in the documentation

[Joseph Herlant]

Hi guys,

This commit deals with a few misspells in the documentation.

One point I'm not sure in the following sentence is if the "unsed"
should be "used" or "unset" (from doc/SPOE.txt):
The engine name must be uniq for a proxy. If no engine name is
provided on the SPOE filter line, the SPOE agent name is unsed by
default.

The patch is attached, but if you want to view the diff online, you
can check: 
https://github.com/haproxy/haproxy/compare/master...aerostitch:doc_typos

Thanks for your help,
Joseph
From a2e89f9e0b17c00222938341f857b1d067abe5af Mon Sep 17 00:00:00 2001
From: Joseph Herlant 
Date: Tue, 13 Nov 2018 16:55:16 -0800
Subject: [PATCH] DOC: fix a few typos in the documentation

This commit deals with a few misspells in the documentation.
---
 doc/51Degrees-device-detection.txt |  2 +-
 doc/SPOE.txt   | 12 ++--
 doc/architecture.txt   |  2 +-
 doc/close-options.txt  |  2 +-
 doc/coding-style.txt   |  6 +++---
 doc/configuration.txt  |  2 +-
 doc/cookie-options.txt |  2 +-
 doc/lua.txt|  6 +++---
 doc/management.txt |  2 +-
 doc/peers-v2.0.txt |  6 +++---
 doc/peers.txt  | 10 +-
 doc/regression-testing.txt |  4 ++--
 12 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/doc/51Degrees-device-detection.txt b/doc/51Degrees-device-detection.txt
index c30cb335..381008ae 100644
--- a/doc/51Degrees-device-detection.txt
+++ b/doc/51Degrees-device-detection.txt
@@ -87,7 +87,7 @@ Here, two headers are created with 51Degrees data, X-51D-DeviceTypeMobileTablet
 and X-51D-Tablet. Any number of headers can be created this way and can be
 named anything. 51d.all( ) invokes the 51degrees fetch. It can be passed up to
 five property names of values to return. Values will be returned in the same
-order, seperated by the 51-degrees-property-separator configured earlier. If a
+order, separated by the 51-degrees-property-separator configured earlier. If a
 property name can't be found the value 'NoData' is returned instead.
 
 In addition to the device properties three additional properties related to the
diff --git a/doc/SPOE.txt b/doc/SPOE.txt
index 2b4cc3b5..59cbafe3 100644
--- a/doc/SPOE.txt
+++ b/doc/SPOE.txt
@@ -146,7 +146,7 @@ found in the SPOE configuration file. All the file is considered to be in the
 same anonymous and implicit scope.
 
 The engine name must be uniq for a proxy. If no engine name is provided on the
-SPOE filter line, the SPOE agent name is unsed by default.
+SPOE filter line, the SPOE agent name is used by default.
 
 2.2. "spoe-agent" section
 --
@@ -192,7 +192,7 @@ groups  ...
   Arguments :
is the name of a SPOE group.
 
-  Groups delcared here must be found in the same engine scope, else an error is
+  Groups declared here must be found in the same engine scope, else an error is
   triggered during the configuration parsing. You can have many "groups" lines.
 
   See also: "spoe-group" section.
@@ -501,7 +501,7 @@ args [name=] ...
 
   When the message is processed, if a sample expression is not available, it is
   set to NULL. Arguments are processed in their declaration order and added in
-  the message in that order. It is possible to declare named arguements.
+  the message in that order. It is possible to declare named arguments.
 
   For example:
 args frontend=fe_id src dst
@@ -717,7 +717,7 @@ actions.
payload. When it is set, the FIN bit must also be set.
 
 
-Frames cannot exceed a maximum size negociated between HAProxy and agents
+Frames cannot exceed a maximum size negotiated between HAProxy and agents
 during the HELLO handshake. Most of time, payload will be small enough to send
 it in one frame. But when supported by the peer, it will be possible to
 fragment huge payload on many frames. This ability is announced during the
@@ -1182,7 +1182,7 @@ IMPORTANT NOTE: By default, for a specific stream, when an abnormal/unexpected
 will disable it for the transaction (request and response).
 See 'option continue-on-error' to bypass this limitation.
 
-To avoid a stream to wait infinitly, you must carefully choose the
+To avoid a stream to wait undefinetly, you must carefully choose the
 acknowledgement timeout. In most of cases, it will be quiet low. But it depends
 on the responsivness of your service.
 
@@ -1219,7 +1219,7 @@ following format:
  fragmented frames, it is the sum of all fragments.
 * qT   : the delay before the request gets out the sending queue. For
  fragmented frames, it is the sum of all fragments.
-* wT   : the delay before the reponse is received. No fragmentation
+* wT   : the delay before the response is received. No fragmentation

[PR] Fix typos in comments and documentation

[PR Bot]

Dear list!

Author: Joseph Herlant 
Number of patches: 1

This is an automated relay of the Github pull request:
   Fix typos in comments and documentation

Patch title(s): 
   Fix typos in comments and documentation

Link:
   https://github.com/haproxy/haproxy/pull/1

Edit locally:
   wget https://github.com/haproxy/haproxy/pull/1.patch && vi 1.patch

Apply locally:
   curl https://github.com/haproxy/haproxy/pull/1.patch | git am -

Description:
   Hi,
   
   I found some typos while reading the documentation so I
   ended up running a tool called `misspell` on the repo that basically
   fixes common misspells.
   Reviewed the result, did some changes, but
   I think we should be ok with what's left here.
   
   Let me know if
   you want to break this change into smaller changes or if there are
   some elements I might have missed.
   
   Thanks
   Jospeh

Instructions:
   This github pull request will be closed automatically; patch should be
   reviewed on the haproxy mailing list (haproxy@formilux.org). Everyone is
   invited to comment, even the patch's author. Please keep the author and
   list CCed in replies. Please note that in absence of any response this
   pull request will be lost.

Ambiguity in documentation for `http-request set-header`

[Thayne McCombs]

The documentation for `http-request set-header` is a little ambiguous about
whether it removes all occurrences of the header if it previously existed
or just the first one. From experimentation it appears it is all
occurrences (which I think is preferable).

May I suggest rewording "except that the header name is first removed if it
existed" to "except that all occurrences of the header name are first
removed if any existed"?

Re: [PATCH] DOC: Fix typos in lua documentation

[Willy Tarreau]

On Thu, Sep 13, 2018 at 01:50:29PM +0100, Bertrand Jacquin wrote:
> Hi,
> 
> Please find attached a patch to fix some typos in the lua documentation.

Applied, thanks Bertrand!
Willy

[PATCH] DOC: Fix typos in lua documentation

[Bertrand Jacquin]

Hi,

Please find attached a patch to fix some typos in the lua documentation.

Cheers,

--
BertrandFrom a8c24069246fc6ba6e9a956963158596ec4a0a3b Mon Sep 17 00:00:00 2001
From: Bertrand Jacquin 
Date: Mon, 10 Sep 2018 21:26:07 +0100
Subject: [PATCH] DOC: Fix typos in lua documentation

---
 doc/lua-api/index.rst  | 114 -
 src/filters.c  |   2 +-
 src/stream_interface.c |   2 +-
 3 files changed, 59 insertions(+), 59 deletions(-)

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 0c79766eb939..553cf521edd3 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -209,7 +209,7 @@ Core class
   configuration file, on the default syslog server if it is configured and on
   the stderr if it is allowed.
 
-  :param integer loglevel: Is the log level asociated with the message. It is a
+  :param integer loglevel: Is the log level associated with the message. It is a
 number between 0 and 7.
   :param string msg: The log content.
   :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
@@ -314,8 +314,8 @@ Core class
   Returns HAProxy core informations. We can found information like the uptime,
   the pid, memory pool usage, tasks number, ...
 
-  These information are also returned by the management sockat via the command
-  "show info". See the management socket documentation fpor more information
+  These information are also returned by the management socket via the command
+  "show info". See the management socket documentation for more information
   about the content of these variables.
 
   :returns: an array of values.
@@ -325,7 +325,7 @@ Core class
   **context**: body, init, task, action
 
   This function returns the current time. The time returned is fixed by the
-  HAProxy core and assures than the hour will be monotnic and that the system
+  HAProxy core and assures than the hour will be monotonic and that the system
   call 'gettimeofday' will not be called too. The time is refreshed between each
   Lua execution or resume, so two consecutive call to the function "now" will
   probably returns the same result.
@@ -338,7 +338,7 @@ Core class
 
   **context**: body, init, task, action
 
-  This function take a string repsenting http date, and returns an integer
+  This function take a string representing http date, and returns an integer
   containing the corresponding date with a epoch format. A valid http date
   me respect the format IMF, RFC850 or ASCTIME.
 
@@ -353,7 +353,7 @@ Core class
 
   **context**: body, init, task, action
 
-  This function take a string repsenting IMF date, and returns an integer
+  This function take a string representing IMF date, and returns an integer
   containing the corresponding date with a epoch format.
 
   :param string date: a date IMF formatted
@@ -371,7 +371,7 @@ Core class
 
   **context**: body, init, task, action
 
-  This function take a string repsenting RFC850 date, and returns an integer
+  This function take a string representing RFC850 date, and returns an integer
   containing the corresponding date with a epoch format.
 
   :param string date: a date RFC859 formatted
@@ -389,7 +389,7 @@ Core class
 
   **context**: body, init, task, action
 
-  This function take a string repsenting ASCTIME date, and returns an integer
+  This function take a string representing ASCTIME date, and returns an integer
   containing the corresponding date with a epoch format.
 
   :param string date: a date ASCTIME formatted
@@ -407,7 +407,7 @@ Core class
 
   **context**: body, init, task, action
 
-  This function take a string repsenting http date, and returns an integer
+  This function take a string representing http date, and returns an integer
   containing the corresponding date with a epoch format.
 
   :param string date: a date http-date formatted
@@ -416,7 +416,7 @@ Core class
 
   **context**: body, init, task, action
 
-  This function take a string repsenting http date, and returns an integer
+  This function take a string representing http date, and returns an integer
   containing the corresponding date with a epoch format.
 
   :param string date: a date http-date formatted
@@ -433,7 +433,7 @@ Core class
 
   **context**: body, init, task, action, sample-fetch, converter
 
-  proxies is a table containing the list of all proxies declared in the
+  Proxies is a table containing the list of all proxies declared in the
   configuration file. The table is indexed by the proxy name, and each entry
   of the proxies table is an object of type :ref:`proxy_class`.
 
@@ -466,9 +466,9 @@ Core class
   * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
 current request or TCP stream.
 
-  * **argX**: this is argument provided throught the HAProxy configuration file.
+  * **argX**: this is argument provided through the HAProxy configuration file.
 
-  Here, an exemple of actio

Re: [PATCH] DOC: add documentation for prio_class and prio_offset sample fetches.

[Willy Tarreau]

On Mon, Aug 13, 2018 at 02:07:57PM -0400, Patrick Hemmer wrote:
> This adds documentation that was missed as part of 268a707.

Oh thank you Patrick, I think I didn't even notice that the sample fetch
functions were already there :-)

Willy

[PATCH] DOC: add documentation for prio_class and prio_offset sample fetches.

[Patrick Hemmer]

This adds documentation that was missed as part of 268a707.
---
 doc/configuration.txt | 11 +++
 1 file changed, 11 insertions(+)


diff --git a/doc/configuration.txt b/doc/configuration.txt
index 48b69a5bd..d11b63185 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -13857,6 +13857,17 @@ nbsrv([]) : integer
   to handle some load. It is useful to report a failure when combined with
   "monitor fail".
 
+prio_class : integer
+  Returns the priority class of the current session for http mode or connection
+  for tcp mode. The value will be that set by the last call to "http-request
+  set-priority-class" or "tcp-request content set-priority-class".
+
+prio_offset : integer
+  Returns the priority offset of the current session for http mode or
+  connection for tcp mode. The value will be that set by the last call to
+  "http-request set-priority-offset" or "tcp-request content
+  set-priority-offset".
+
 proc : integer
   Returns an integer value corresponding to the position of the process calling
   the function, between 1 and global.nbproc. This is useful for logging and

mistake in email-alert to documentation

[Filip Cornelissen | SkillSource]

	Found a mistake in the documentation.

	 

	see: http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#4.2-email-alert%20to

	or: https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt#L3515

	 

	the line:

	Also requires "email-alert mailers" and "email-alert to" to be set

	 

	should be:

	Also requires "email-alert mailers" and "email-alert from" to be set

	 

	
	
	 

	
	
		
			 
		
			Kind regards,
		
			 
		
			Filip Cornelissen | SkillSource
		
			 
		
			
088 - 6500 250
			
f.cornelis...@skillsource.nl
			
www.skillsource.nl
		
		
			 
		
			 
	
	

	 
 

Re: [PATCH 1/1] DOC/MINOR: clean up LUA documentation re: servers & array/table.

[Willy Tarreau]

On Thu, May 03, 2018 at 09:20:15AM +0200, Thierry Fournier wrote:
> Hi Patrick,
> 
> Thanks for cleaning the Lua doc.
> 
> Willy, could you apply these patches ?

Now done, thanks!

Willy

Re: [PATCH 1/1] DOC/MINOR: clean up LUA documentation re: servers & array/table.

[Thierry Fournier]

Hi Patrick,

Thanks for cleaning the Lua doc.

Willy, could you apply these patches ?
Theses patch could be backported from 1.8 to 1.6, but it is not so important.

Thierry


> On 2 May 2018, at 03:30, Patrick Hemmer  wrote:
> 
> 
> * A few typos
> * Fix definitions of values which are tables, not arrays.
> * Consistent US English naming for "server" instead of "serveur".
> ---
> doc/lua-api/index.rst | 88
> ++-
> 1 file changed, 45 insertions(+), 43 deletions(-)
> 
> 
> <0001-DOC-MINOR-clean-up-LUA-documentation-re-servers-arra.patch>

[PATCH 1/1] DOC/MINOR: clean up LUA documentation re: servers & array/table.

[Patrick Hemmer]

ly draining stiky connections.
+  Return true if the server is currently draining sticky connections.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
@@ -930,7 +932,7 @@ Server class
 
 .. js:function:: Server.set_weight(sv, weight)
 
-  Dynamically change the weight of the serveur. See the management socket
+  Dynamically change the weight of the server. See the management socket
   documentation for more information about the format of the string.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
@@ -939,7 +941,7 @@ Server class
 
 .. js:function:: Server.get_weight(sv)
 
-  This function returns an integer representing the serveur weight.
+  This function returns an integer representing the server weight.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
@@ -947,16 +949,16 @@ Server class
 
 .. js:function:: Server.set_addr(sv, addr)
 
-  Dynamically change the address of the serveur. See the management socket
+  Dynamically change the address of the server. See the management socket
   documentation for more information about the format of the string.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
-  :param string weight: A string describing the server address.
+  :param string addr: A string describing the server address.
 
 .. js:function:: Server.get_addr(sv)
 
-  Returns a string describing the address of the serveur.
+  Returns a string describing the address of the server.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
@@ -968,7 +970,7 @@ Server class
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
-  :returns: a key/value array containing stats
+  :returns: a key/value table containing stats
 
 .. js:function:: Server.shut_sess(sv)
 
@@ -1085,7 +1087,7 @@ Listener class
 
   :param class_listener ls: A :ref:`listener_class` which indicates the
 manipulated listener.
-  :returns: a key/value array containing stats
+  :returns: a key/value table containing stats
 
 .. _concat_class:
 
@@ -1169,7 +1171,7 @@ Fetches class
   usage. they are the chapters 7.3.2 to 7.3.6.
 
   **warning** some sample fetches are not available in some context. These
-  limitations are specified in this documentation when theire useful.
+  limitations are specified in this documentation when they're useful.
 
   :see: :js:attr:`TXN.f`
   :see: :js:attr:`TXN.sf`
@@ -1345,13 +1347,13 @@ HTTP class
 
 .. js:function:: HTTP.req_get_headers(http)
 
-  Returns an array containing all the request headers.
+  Returns a table containing all the request headers.
 
   :param class_http http: The related http object.
-  :returns: array of headers.
+  :returns: table of headers.
   :see: :js:func:`HTTP.res_get_headers`
 
-  This is the form of the returned array:
+  This is the form of the returned table:
 
 .. code-block:: lua
 
@@ -1366,13 +1368,13 @@ HTTP class
 
 .. js:function:: HTTP.res_get_headers(http)
 
-  Returns an array containing all the response headers.
+  Returns a table containing all the response headers.
 
   :param class_http http: The related http object.
-  :returns: array of headers.
+  :returns: table of headers.
   :see: :js:func:`HTTP.req_get_headers`
 
-  This is the form of the returned array:
+  This is the form of the returned table:
 
 .. code-block:: lua
 
@@ -2211,12 +2213,12 @@ AppletHTTP class
 
 .. js:attribute:: AppletHTTP.headers
 
-  :returns: array
+  :returns: table
 
-  The attribute headers returns an array containing the HTTP
+  The attribute headers returns a table containing the HTTP
   headers. The header names are always in lower case. As the header name can be
   encountered more than once in each request, the value is indexed with 0 as
-  first index value. The array have this form:
+  first index value. The table have this form:
 
 .. code-block:: lua
 

[PATCH 0/1] Re: DOC/MINOR: clean up LUA documentation re: servers & array/table.

[Patrick Hemmer]

Another rebase on this as I found more table/array issues in the
documentation. I went through the whole doc this time, so this should be
all of it.

Patrick Hemmer (1):
  DOC/MINOR: clean up LUA documentation re: servers & array/table.

 doc/lua-api/index.rst | 88
++-
 1 file changed, 45 insertions(+), 43 deletions(-)

-- 
2.16.3

[PATCH 1/1] DOC/MINOR: clean up LUA documentation re: servers & array/table.

[Patrick Hemmer]

* A few typos
* Move note about duplicate frontend/backend duplicate naming.
* Consistent US English naming for "server" instead of "serveur".
* Properly identify tables as tables instead of arrays, and provide
information on index. -- LUA defines an array as a table indexed with
integers. By that definition many of the things being called arrays
weren't arrays.

---
 doc/lua-api/index.rst | 60
++-
 1 file changed, 31 insertions(+), 29 deletions(-)


diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index a83bbde01..8be37e830 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -169,9 +169,9 @@ Core class
 
   **context**: task, action, sample-fetch, converter
 
-  This attribute is an array of declared proxies (frontend and backends). Each
-  proxy give an access to his list of listeners and servers. Each entry is of
-  type :ref:`proxy_class`
+  This attribute is a table of declared proxies (frontend and backends). Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by proxy name, and each entry is of type :ref:`proxy_class`.
 
   Warning, if you are declared frontend and backend with the same name, only one
   of these are listed.
@@ -183,12 +183,9 @@ Core class
 
   **context**: task, action, sample-fetch, converter
 
-  This attribute is an array of declared proxies with backend capability. Each
-  proxy give an access to his list of listeners and servers. Each entry is of
-  type :ref:`proxy_class`
-
-  Warning, if you are declared frontend and backend with the same name, only one
-  of these are listed.
+  This attribute is a table of declared proxies with backend capability. Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by the backend name, and each entry is of type :ref:`proxy_class`.
 
   :see: :js:attr:`core.proxies`
   :see: :js:attr:`core.frontends`
@@ -197,12 +194,9 @@ Core class
 
   **context**: task, action, sample-fetch, converter
 
-  This attribute is an array of declared proxies with frontend capability. Each
-  proxy give an access to his list of listeners and servers. Each entry is of
-  type :ref:`proxy_class`
-
-  Warning, if you are declared frontend and backend with the same name, only one
-  of these are listed.
+  This attribute is a table of declared proxies with frontend capability. Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by the frontend name, and each entry is of type :ref:`proxy_class`.
 
   :see: :js:attr:`core.proxies`
   :see: :js:attr:`core.backends`
@@ -439,9 +433,12 @@ Core class
 
   **context**: body, init, task, action, sample-fetch, converter
 
-  proxies is an array containing the list of all proxies declared in the
-  configuration file. Each entry of the proxies array is an object of type
-  :ref:`proxy_class`
+  proxies is a table containing the list of all proxies declared in the
+  configuration file. The table is indexed by the proxy name, and each entry
+  of the proxies table is an object of type :ref:`proxy_class`.
+
+  Warning, if you have declared a frontend and backend with the same name, only
+  one of these are listed.
 
 .. js:function:: core.register_action(name, actions, func [, nb_args])
 
@@ -852,13 +849,14 @@ Proxy class
 
 .. js:attribute:: Proxy.servers
 
-  Contain an array with the attached servers. Each server entry is an object of
-  type :ref:`server_class`.
+  Contain a table with the attached servers. The table is indexed by server
+  name, and each server entry is an object of type :ref:`server_class`.
 
 .. js:attribute:: Proxy.listeners
 
-  Contain an array with the attached listeners. Each listeners entry is an
-  object of type :ref:`listener_class`.
+  Contain a table with the attached listeners. The table is indexed by listener
+  name, and each each listeners entry is an object of type
+  :ref:`listener_class`.
 
 .. js:function:: Proxy.pause(px)
 
@@ -920,9 +918,13 @@ Proxy class
 Server class
 
 
+.. js:class:: Server
+
+  This class provides a way for manipulating servers and retrieving information.
+
 .. js:function:: Server.is_draining(sv)
 
-  Return true if the server is currently draining stiky connections.
+  Return true if the server is currently draining sticky connections.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
@@ -930,7 +932,7 @@ Server class
 
 .. js:function:: Server.set_weight(sv, weight)
 
-  Dynamically change the weight of the serveur. See the management socket
+  Dynamically change the weight of the server. See the management socket
   documentation for more information about the format of the string.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
@@ -939,7 +941,7 @@ Server class
 
 .. js:function:: Server.get_weight(sv)
 
-  This function returns an integer representing th

[PATCH] DOC/MINOR: clean up LUA documentation re: servers & array/table.

[Patrick Hemmer]

* A few typos
* Consistent US English naming for "server" instead of "serveur".
* Properly identify tables as tables instead of arrays. And provide
information on index. LUA defines an array as a table indexed with
integers. By that definition many of the things being called arrays
weren't arrays.

---
 doc/lua-api/index.rst | 49
+++--
 1 file changed, 27 insertions(+), 22 deletions(-)


diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index a83bbde01..7a77e46ee 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -169,9 +169,9 @@ Core class
 
   **context**: task, action, sample-fetch, converter
 
-  This attribute is an array of declared proxies (frontend and backends). Each
-  proxy give an access to his list of listeners and servers. Each entry is of
-  type :ref:`proxy_class`
+  This attribute is a table of declared proxies (frontend and backends). Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by proxy name, and each entry is of type :ref:`proxy_class`.
 
   Warning, if you are declared frontend and backend with the same name, only one
   of these are listed.
@@ -183,9 +183,9 @@ Core class
 
   **context**: task, action, sample-fetch, converter
 
-  This attribute is an array of declared proxies with backend capability. Each
-  proxy give an access to his list of listeners and servers. Each entry is of
-  type :ref:`proxy_class`
+  This attribute is a table of declared proxies with backend capability. Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by the backend name, and each entry is of type :ref:`proxy_class`.
 
   Warning, if you are declared frontend and backend with the same name, only one
   of these are listed.
@@ -197,9 +197,9 @@ Core class
 
   **context**: task, action, sample-fetch, converter
 
-  This attribute is an array of declared proxies with frontend capability. Each
-  proxy give an access to his list of listeners and servers. Each entry is of
-  type :ref:`proxy_class`
+  This attribute is a table of declared proxies with frontend capability. Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by the frontend name, and each entry is of type :ref:`proxy_class`.
 
   Warning, if you are declared frontend and backend with the same name, only one
   of these are listed.
@@ -439,8 +439,8 @@ Core class
 
   **context**: body, init, task, action, sample-fetch, converter
 
-  proxies is an array containing the list of all proxies declared in the
-  configuration file. Each entry of the proxies array is an object of type
+  proxies is a table containing the list of all proxies declared in the
+  configuration file. Each entry of the proxies table is an object of type
   :ref:`proxy_class`
 
 .. js:function:: core.register_action(name, actions, func [, nb_args])
@@ -852,13 +852,14 @@ Proxy class
 
 .. js:attribute:: Proxy.servers
 
-  Contain an array with the attached servers. Each server entry is an object of
-  type :ref:`server_class`.
+  Contain a table with the attached servers. The table is indexed by server
+  name, and each server entry is an object of type :ref:`server_class`.
 
 .. js:attribute:: Proxy.listeners
 
-  Contain an array with the attached listeners. Each listeners entry is an
-  object of type :ref:`listener_class`.
+  Contain a table with the attached listeners. The table is indexed by listener
+  name, and each each listeners entry is an object of type
+  :ref:`listener_class`.
 
 .. js:function:: Proxy.pause(px)
 
@@ -920,9 +921,13 @@ Proxy class
 Server class
 
 
+.. js:class:: Server
+
+  This class provides a way for manipulating servers and retrieving information.
+
 .. js:function:: Server.is_draining(sv)
 
-  Return true if the server is currently draining stiky connections.
+  Return true if the server is currently draining sticky connections.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
@@ -930,7 +935,7 @@ Server class
 
 .. js:function:: Server.set_weight(sv, weight)
 
-  Dynamically change the weight of the serveur. See the management socket
+  Dynamically change the weight of the server. See the management socket
   documentation for more information about the format of the string.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
@@ -939,7 +944,7 @@ Server class
 
 .. js:function:: Server.get_weight(sv)
 
-  This function returns an integer representing the serveur weight.
+  This function returns an integer representing the server weight.
 
   :param class_server sv: A :ref:`server_class` which indicates the manipulated
 server.
@@ -947,16 +952,16 @@ Server class
 
 .. js:function:: Server.set_addr(sv, addr)
 
-  Dynamically change the address of the serveur. See the management socket
+  Dynamically change the address of the server. 

Re: [Patch] Error in Lua documentation

[Willy Tarreau]

On Mon, Feb 12, 2018 at 02:50:51PM +0100, Thierry FOURNIER wrote:
> Hi,
> 
> This is a small patch about the Lua documentation.
> it should be backported in 1.8
> 
> Note that the function prototype is compatible with old versions.

Applied, thank you Thierry.

Willy

[Patch] Error in Lua documentation

[Thierry FOURNIER]

Hi,

This is a small patch about the Lua documentation.
it should be backported in 1.8

Note that the function prototype is compatible with old versions.

Thierry

>From 4feaa411b6cca0b3a57ebe16c13ce056d93eb74a Mon Sep 17 00:00:00 2001
From: Thierry FOURNIER 
Date: Mon, 12 Feb 2018 14:46:54 +0100
Subject: [PATCH] DOC: new prototype for function "register_action()"

This patch should e backported in version 1.8
---
 doc/lua-api/index.rst | 27 +--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 7fe609f..e7aa425 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -443,7 +443,7 @@ Core class
   configuration file. Each entry of the proxies array is an object of type
   :ref:`proxy_class`
 
-.. js:function:: core.register_action(name, actions, func)
+.. js:function:: core.register_action(name, actions, func [, nb_args])
 
   **context**: body
 
@@ -455,18 +455,22 @@ Core class
   :param table actions: is a table of string describing the HAProxy actions who
 want to register to. The expected actions are 'tcp-req',
 'tcp-res', 'http-req' or 'http-res'.
+  :param integer nb_args: is the expected number of argument for the action.
+  By default the value is 0.
   :param function func: is the Lua function called to work as converter.
 
   The prototype of the Lua function used as argument is:
 
 .. code-block:: lua
 
-  function(txn)
+  function(txn [, arg1 [, arg2]])
 ..
 
   * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
 current request or TCP stream.
 
+  * **argX**: this is argument provided throught the HAProxy configuration file.
+
   Here, an exemple of action registration. the action juste send an 'Hello world'
   in the logs.
 
@@ -488,7 +492,26 @@ Core class
   frontend http_frt
 mode http
 http-request lua.hello-world
+..
+
+  A second example using aruments
+
+.. code-block:: lua
+
+  function hello_world(txn, arg)
+ txn:Info("Hello world for " .. arg)
+  end
+  core.register_action("hello-world", { "tcp-req", "http-req" }, hello_world, 2)
+..
 
+  This example code is used in HAproxy configuration like this:
+
+::
+
+  frontend tcp_frt
+mode tcp
+tcp-request content lua.hello-world everybody
+..
 .. js:function:: core.register_converters(name, func)
 
   **context**: body
-- 
2.9.5

Re: Encrypted Passwords Documentation Patch

[Willy Tarreau]

On Mon, Nov 06, 2017 at 05:06:37PM +0100, Daniel Schneller wrote:
> It adds a warning about the potentially significant CPU cost the modern
> algorithms with their thousands of hashing rounds can incur. In our case it
> made the difference between haproxy's CPU usage being hardly noticeable at all
> to it almost eating a full core, even for a not very busy site.

Good point! Now applied, thanks Daniel.

Willy

Encrypted Passwords Documentation Patch

[Daniel Schneller]

Hi!

Attached find a documentation patch for the encrypted passwords in userlists.

It adds a warning about the potentially significant CPU cost the modern
algorithms with their thousands of hashing rounds can incur. In our case it
made the difference between haproxy’s CPU usage being hardly noticeable at all
to it almost eating a full core, even for a not very busy site.

Tested with 1.6, but this applies to all versions, if I am not mistaken.

Cheers,
Daniel


-- 
Daniel Schneller
Principal Cloud Engineer
 
CenterDevice GmbH  | Hochstraße 11
   | 42697 Solingen
tel: +49 1754155711| Deutschland
daniel.schnel...@centerdevice.de   | www.centerdevice.de

Geschäftsführung: Dr. Patrick Peschlow, Dr. Lukas Pustina,
Michael Rosbach, Handelsregister-Nr.: HRB 18655,
HR-Gericht: Bonn, USt-IdNr.: DE-815299431



0001-DOC-Add-note-about-encrypted-password-CPU-usage.patch
Description: Binary data

[PATCH v3 7/9] DOC: add documentation for the master-worker mode

[William Lallemand]

---
 doc/configuration.txt | 16 
 doc/management.txt| 15 +--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index ad7d3a8..5fa49d3 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -803,6 +803,20 @@ lua-load 
   This global directive loads and executes a Lua file. This directive can be
   used multiple times.
 
+master-worker [exit-on-failure]
+  Master-worker mode. It is equivalent to the command line "-W" argument.
+  This mode will launch a "master" which will monitor the "workers". Using
+  this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
+  the master.  The master-worker mode is compatible either with the foreground
+  or daemon mode. It is recommended to use this mode with multiprocess and
+  systemd.
+  The "exit-on-failure" option allows the master to kill every workers and
+  exit when one of the current workers died. It is convenient to combine this
+  option with Restart=on-failure in a systemd unit file in order to relaunch
+  the whole process.
+
+  See alors "-W" in the management guide.
+
 nbproc 
   Creates  processes when going daemon. This requires the "daemon"
   mode. By default, only one process is created, which is the recommended mode
@@ -10431,6 +10445,8 @@ defer-accept
 expose-fd listeners
   This option is only usable with the stats socket. It gives your stats socket
   the capability to pass listeners FD to another HAProxy process.
+  During a reload with the master-worker mode, the process is automatically
+  reexecuted adding -x and one of the stats socket with this option.
   See alors "-x" in the management guide.
 
 force-sslv3
diff --git a/doc/management.txt b/doc/management.txt
index 64d6a2d..df091bb 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -160,8 +160,6 @@ list of options is :
 configuration. It is recommended to always force it in any init script so
 that a faulty configuration doesn't prevent the system from booting.
 
-  -Ds : work in systemd mode. Only used by the systemd wrapper.
-
   -L  : change the local peer name to , which defaults to the local
 hostname. This is used only with peers replication.
 
@@ -171,6 +169,13 @@ list of options is :
   -V : enable verbose mode (disables quiet mode). Reverts the effect of "-q" or
 "quiet".
 
+  -W : master-worker mode. It is equivalent to the "master-worker" keyword in
+the "global" section of the configuration. This mode will launch a "master"
+which will monitor the "workers". Using this mode, you can reload HAProxy
+directly by sending a SIGUSR2 signal to the master.  The master-worker mode
+is compatible either with the foreground or daemon mode.  It is
+recommended to use this mode with multiprocess and systemd.
+
   -c : only performs a check of the configuration files and exits before trying
 to bind. The exit status is zero if everything is OK, or non-zero if an
 error is encountered.
@@ -419,6 +424,12 @@ reload or restart, so that they are sent at the latest 
possible moment and only
 if absolutely required. This is what is performed by the "-st" (hard) and "-sf"
 (graceful) options respectively.
 
+In master-worker mode, it is not needed to start a new haproxy process in
+order to reload the configuration. The master process reacts to the SIGUSR2
+signal by reexecuting itself with the -sf parameter followed by the PIDs of
+the workers. The master will then parse the configuration file and fork new
+workers.
+
 To understand better how these signals are used, it is important to understand
 the whole restart mechanism.
 
-- 
2.10.2

[PATCH 7/9] DOC: add documentation for the master-worker mode

[William Lallemand]

---
 doc/configuration.txt | 16 
 doc/management.txt| 15 +--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index ad7d3a8..5fa49d3 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -803,6 +803,20 @@ lua-load 
   This global directive loads and executes a Lua file. This directive can be
   used multiple times.
 
+master-worker [exit-on-failure]
+  Master-worker mode. It is equivalent to the command line "-W" argument.
+  This mode will launch a "master" which will monitor the "workers". Using
+  this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
+  the master.  The master-worker mode is compatible either with the foreground
+  or daemon mode. It is recommended to use this mode with multiprocess and
+  systemd.
+  The "exit-on-failure" option allows the master to kill every workers and
+  exit when one of the current workers died. It is convenient to combine this
+  option with Restart=on-failure in a systemd unit file in order to relaunch
+  the whole process.
+
+  See alors "-W" in the management guide.
+
 nbproc 
   Creates  processes when going daemon. This requires the "daemon"
   mode. By default, only one process is created, which is the recommended mode
@@ -10431,6 +10445,8 @@ defer-accept
 expose-fd listeners
   This option is only usable with the stats socket. It gives your stats socket
   the capability to pass listeners FD to another HAProxy process.
+  During a reload with the master-worker mode, the process is automatically
+  reexecuted adding -x and one of the stats socket with this option.
   See alors "-x" in the management guide.
 
 force-sslv3
diff --git a/doc/management.txt b/doc/management.txt
index 64d6a2d..df091bb 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -160,8 +160,6 @@ list of options is :
 configuration. It is recommended to always force it in any init script so
 that a faulty configuration doesn't prevent the system from booting.
 
-  -Ds : work in systemd mode. Only used by the systemd wrapper.
-
   -L  : change the local peer name to , which defaults to the local
 hostname. This is used only with peers replication.
 
@@ -171,6 +169,13 @@ list of options is :
   -V : enable verbose mode (disables quiet mode). Reverts the effect of "-q" or
 "quiet".
 
+  -W : master-worker mode. It is equivalent to the "master-worker" keyword in
+the "global" section of the configuration. This mode will launch a "master"
+which will monitor the "workers". Using this mode, you can reload HAProxy
+directly by sending a SIGUSR2 signal to the master.  The master-worker mode
+is compatible either with the foreground or daemon mode.  It is
+recommended to use this mode with multiprocess and systemd.
+
   -c : only performs a check of the configuration files and exits before trying
 to bind. The exit status is zero if everything is OK, or non-zero if an
 error is encountered.
@@ -419,6 +424,12 @@ reload or restart, so that they are sent at the latest 
possible moment and only
 if absolutely required. This is what is performed by the "-st" (hard) and "-sf"
 (graceful) options respectively.
 
+In master-worker mode, it is not needed to start a new haproxy process in
+order to reload the configuration. The master process reacts to the SIGUSR2
+signal by reexecuting itself with the -sf parameter followed by the PIDs of
+the workers. The master will then parse the configuration file and fork new
+workers.
+
 To understand better how these signals are used, it is important to understand
 the whole restart mechanism.
 
-- 
2.10.2

Re: clarification on documentation for sticky counter tracking duration

[Aleksandar Lazic]

Hi Patrick Hemmer.

Patrick Hemmer have written on Thu, 4 May 2017 19:41:59 -0400:

> I'm looking to get some clarification around the documentation for the
> duration of sticky counter tracking. There are 2 specific points I'm a
> little confused on.
> 
> 1. Under the documentation for `tcp-request content`, it says:
> > In case of HTTP keep-alive with the client, all tcp-request
> > content  
> rules are evaluated again, so haproxy keeps a record of what sticky
> counters were assigned by a "tcp-request connection" versus a
> "tcp-request content" rule, and flushes all the content-related ones
> after processing an HTTP request
> 
> This sounds like if I were to use `tcp-request content track-sc0 src`,
> that after the http request is finished processing, the sticky counter
> for the source IP will be stop being tracked. However this does not
> appear to be the case as when I log sc0_conn_cur, it is counting
> clients that are sitting idle between http requests (using http
> keep-alive).
> 
> 2. Under the documentation for `http-request track-sc0`, it says:
> > Once a "track-sc*" rule is executed, the key is looked up in the
> > table  
> and if it is not found, an entry is allocated for it. Then a pointer
> to that entry is kept during all the session's life
> 
> This sounds like the sticky counter is tracked for the duration of the
> http session: "entry is kept during all the **session's** life".
> However this does not seem to be the case as when I log sc0_conn_cur,
> clients that are sitting idle between http requests are not counted.
> 
> 
> Am I interpreting the documentation incorrectly, or is the
> documentation incorrect?

Buh that's difficult to answer but maybe you can take a look into the
intro doc.

http://www.haproxy.org/download/1.7/doc/intro.txt

There is a section about Stick-tables

3.3.11. Basic features : Stick-tables

There is also a descritption in the source.
http://git.haproxy.org/?p=haproxy-1.7.git;a=blob;f=include/types/stick_table.h;hb=0f97bdec990a8f06742efcedf9fd419443300d63#l185

###
 185  * What's the purpose of there two macro:
 186  *   - STKCTR_TRACK_BACKEND indicates that a tracking pointer was set from 
the backend
 187  *and thus that when a keep-alive request goes to another backend, the 
track
 188  *must cease.
 189  *
 190  *   - STKCTR_TRACK_CONTENT indicates that the tracking pointer was set in 
a
 191  *content-aware rule (tcp-request content or http-request) and that the
 192  *tracking has to be performed in the stream and not in the session, 
and
 193  *will cease for a new keep-alive request over the same
 connection.
###

Does this information helps you to understand the behavior?

> -Patrick

Regards
Aleks

clarification on documentation for sticky counter tracking duration

[Patrick Hemmer]

I'm looking to get some clarification around the documentation for the
duration of sticky counter tracking. There are 2 specific points I'm a
little confused on.

1. Under the documentation for `tcp-request content`, it says:
> In case of HTTP keep-alive with the client, all tcp-request content
rules are evaluated again, so haproxy keeps a record of what sticky
counters were assigned by a "tcp-request connection" versus a
"tcp-request content" rule, and flushes all the content-related ones
after processing an HTTP request

This sounds like if I were to use `tcp-request content track-sc0 src`,
that after the http request is finished processing, the sticky counter
for the source IP will be stop being tracked. However this does not
appear to be the case as when I log sc0_conn_cur, it is counting clients
that are sitting idle between http requests (using http keep-alive).

2. Under the documentation for `http-request track-sc0`, it says:
> Once a "track-sc*" rule is executed, the key is looked up in the table
and if it is not found, an entry is allocated for it. Then a pointer to
that entry is kept during all the session's life

This sounds like the sticky counter is tracked for the duration of the
http session: "entry is kept during all the **session's** life". However
this does not seem to be the case as when I log sc0_conn_cur, clients
that are sitting idle between http requests are not counted.


Am I interpreting the documentation incorrectly, or is the documentation
incorrect?


-Patrick

Re: Bug in documentation

[Willy Tarreau]

Hi Dave,

On Tue, Mar 28, 2017 at 03:11:09PM +, Dave J wrote:
> Hello
> 
> I've been studying the documentation at
> http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt and have found
> that in the code sample at the bottom there is a bug.  This is also present
> in version 1.7 of the documentation: i haven't looked any further back than
> that.  The line
> 
> size = 16 + hdr.v2.len;
> 
> needs to convert the value of hdr.v2.len to a host short, so it should be
> 
> size = 16 + ntohs(hdr.v2.len);

You're totally right.

> This isn't a major problem, as when stepping through the code the problem can
> be quite quickly spotted, but it just seems a shame to have this little error
> spoil what is an excellent example.
> 
> Sorry if this has been mentioned before; I did take a look but couldn't find
> any mention of it.

It's the first report. Feel free make a patch out of it and to submit
it as your first contribution. Please check CONTRIBUTING then run
"git log doc/proxy-protocol.txt" to get inspired for your commit message :-)

Thanks,
Willy

Bug in documentation

[Dave J]

Hello

I've been studying the documentation at 
http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt and have found that 
in the code sample at the bottom there is a bug.  This is also present in 
version 1.7 of the documentation: i haven't looked any further back than that.  
The line

size = 16 + hdr.v2.len;

needs to convert the value of hdr.v2.len to a host short, so it should be

size = 16 + ntohs(hdr.v2.len);

This isn't a major problem, as when stepping through the code the problem can 
be quite quickly spotted, but it just seems a shame to have this little error 
spoil what is an excellent example.

Sorry if this has been mentioned before; I did take a look but couldn't find 
any mention of it.

Thanks.

Re: [PATCH 2/2] DOC: "block" deny_status documentation.

[Willy Tarreau]

> -block { if | unless }  (deprecated)
> +block [deny_status ] { if | unless }  (deprecated)

I'd rather not add details suggesting how to do side-effect things to
a deprecated keyword. It supports it only because it's being emulated
using "http-request deny", so better not encourage its use anymore.

Thanks,
Willy

[PATCH 2/2] DOC: "block" deny_status documentation.

[Jarno Huuskonen]

---
 doc/configuration.txt | 16 +---
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/doc/configuration.txt b/doc/configuration.txt
index b66267e..775781d 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -2468,17 +2468,18 @@ bind-process [ all | odd | even | [-] ] ...
   See also : "nbproc" in global section, and "process" in section 5.1.
 
 
-block { if | unless }  (deprecated)
+block [deny_status ] { if | unless }  (deprecated)
   Block a layer 7 request if/unless a condition is matched
   May be used in sections :   defaults | frontend | listen | backend
  no|yes   |   yes  |   yes
 
   The HTTP request will be blocked very early in the layer 7 processing
-  if/unless  is matched. A 403 error will be returned if the request
-  is blocked. The condition has to reference ACLs (see section 7). This is
-  typically used to deny access to certain sensitive resources if some
-  conditions are met or not met. There is no fixed limit to the number of
-  "block" statements per instance.
+  if/unless  is matched. A 403 error or optionally the status
+  code specified as an argument to "deny_status" will be returned if the
+  request is blocked. The condition has to reference ACLs (see section 7).
+  This is typically used to deny access to certain sensitive resources if
+  some conditions are met or not met. There is no fixed limit to the
+  number of "block" statements per instance.
 
   This form is deprecated, do not use it in any new configuration, use the new
   "http-request deny" instead.
@@ -2489,7 +2490,8 @@ block { if | unless }  (deprecated)
 acl local_dsthdr(host) -i localhost
 block if invalid_src || local_dst
 
-  See section 7 about ACL usage.
+  See also : "http-request deny", "http-response deny" as well as
+section 7 about ACL usage.
 
 
 capture cookie  len 
-- 
1.8.3.1

Re: [PATCH 2/2] DOC: "block" deny_status documentation.

[Jarno Huuskonen]

Hi,

These patches update "block" keyword documentation.

First patch adds deprecated notice to "block" (haproxy-1.7.1 
warns if you have "block" in your config:
"The 'block' directive is now deprecated in favor...").

Second patch documents block [deny_status ] usage.
Both patches are against 1.7.1 but should apply cleanly to 1.8.

-Jarno

-- 
Jarno Huuskonen

Re: missing documentation on 51degrees samples

[haproxy]

Ping?

-Patrick

On 2016/10/7 13:27, Patrick Hemmer wrote:
> The documentation doesn't mention the sample fetcher `51d.all`, nor
> the converter `51d.single`. The only place they're mentioned is the
> repo README.
>
> Also the documentation for `51degrees-property-name-list` indicates it
> takes an optional single string argument (`[]`), rather than
> multiple string arguments (`...`). This led me to expect it
> was comma delimited, which ended up not working.
>
> -Patrick

Re: [PATCH] MINOR: stats: correct documentation of process ID for typed output

[Willy Tarreau]

Hi Simon,

On Mon, Nov 21, 2016 at 05:00:24PM +0100, Simon Horman wrote:
> The process ID appears at the end of the first column rather than
> the line.

Thank you, applied.

Willy

[PATCH] MINOR: stats: correct documentation of process ID for typed output

[Simon Horman]

The process ID appears at the end of the first column rather than
the line.
---
 doc/management.txt | 12 +++-
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/management.txt b/doc/management.txt
index 751621c0392b..f42c0712012e 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -1802,8 +1802,9 @@ show info [typed]
   11.PoolFailed.1:MCP:u32:0
   (...)
 
-  In the typed format, the presence of the process ID at the end of the line
-  makes it very easy to visually aggregate outputs from multiple processes.
+  In the typed format, the presence of the process ID at the end of the
+  first column makes it very easy to visually aggregate outputs from
+  multiple processes.
   Example :
 
   $ ( echo show info typed | socat /var/run/haproxy.sock1 ;\
@@ -2067,9 +2068,10 @@ show stat [  ] [typed]
 B.3.0.55.lastsess.1:MMP:s32:-1
 (...)
 
-  In the typed format, the presence of the process ID at the end of the line
-  makes it very easy to visually aggregate outputs from multiple processes, as
-  show in the example below where each line appears for each process :
+  In the typed format, the presence of the process ID at the end of the
+  first column makes it very easy to visually aggregate outputs from
+  multiple processes, as show in the example below where each line appears
+  for each process :
 
 $ ( echo show stat typed | socat /var/run/haproxy.sock1 - ; \
 echo show stat typed | socat /var/run/haproxy.sock2 - ) | \
-- 
2.7.0.rc3.207.g0ac5344

missing documentation on 51degrees samples

[Patrick Hemmer]

The documentation doesn't mention the sample fetcher `51d.all`, nor the
converter `51d.single`. The only place they're mentioned is the repo README.

Also the documentation for `51degrees-property-name-list` indicates it
takes an optional single string argument (`[]`), rather than
multiple string arguments (`...`). This led me to expect it was
comma delimited, which ended up not working.

-Patrick

Re: HTML documentation : work in progress

[Igor Cicimov]

On 4 Jul 2016 8:35 am, "Cyril Bonté"  wrote:
>
> Hi all,
>
> this was a productive week-end and the new documentation is nearly ready.
To celebrate this, I've already decided to make it official, despite there
is stille some work to do.
>
> The links provided in my previous mail are still working and will become
the official ones, and everything is also available from the index page :
>
> http://cbonte.github.io/haproxy-dconv/
>
> Important change :
> I've decided to remove the search box. It was a funny toy but some people
reported that they expected it was a full text search box, which was not
true, and the library behind it looks to not be maintained anymore. To
replace the feature, I've added tabs at the left : one to navigate in the
chapters, another to list all the keywords.
> This will allow to use only search tool : the one provided by the browser
;-)
>
> Now, I'll try to work on less critical tasks :
> - remove the old documentation files and redirect to the new ones.
> - fix the parsing issues I still have at some places (mainly false
positives on keyword detection).
> - add a filter box in the keywords tab.
>
> Cheers,
>
>
> Le 27/06/2016 à 23:40, Cyril Bonté a écrit :
>>
>> Hi all,
>>
>> It's been monthes since haproxy has introduced new documentation files
>> in 1.6 and 1.7-dev (ie. intro.txt, management.txt, ...). Until now, I
>> hardly found time to include them in the HTML documentation. It's time
>> to seriously work on this issue !
>>
>> There is quite a lot of things to do before I can say everything is
>> ready, but let's go ! This means that things will break for some days.
>> At least, currently I've disabled the job that regenerates the
>> documentations automatically until things become more stable again (New
>> documentation commits won't appear).
>>
>> I'm also thinking of reorganizing the documentation with one directory
>> per major version (1.4, 1.5, 1.6, 1.7).
>>
>> Tasks in the highest priorities :
>> - allow to navigate between files
>> - search keywords in all files
>> - fix rendering issues (I know there are several parts that are not
>> correctly parsed)
>>
>> As an early preview those files are available here :
>> - haproxy 1.4
>> http://cbonte.github.io/haproxy-dconv/1.4/configuration.html
>>
>> - haproxy 1.5
>> http://cbonte.github.io/haproxy-dconv/1.5/configuration.html
>>
>> - haproxy 1.6
>> http://cbonte.github.io/haproxy-dconv/1.6/intro.html
>> http://cbonte.github.io/haproxy-dconv/1.6/configuration.html
>> http://cbonte.github.io/haproxy-dconv/1.6/management.html
>>
>> - haproxy 1.7
>> http://cbonte.github.io/haproxy-dconv/1.7/intro.html
>> http://cbonte.github.io/haproxy-dconv/1.7/configuration.html
>> http://cbonte.github.io/haproxy-dconv/1.7/management.html
>>
>
>
> --
> Cyril Bonté
>

Awesome job!

Re: HTML documentation : work in progress

[ge...@riseup.net]

Hi Cyril,

On 16-07-05 19:17:30, Willy Tarreau wrote:
> Thanks for doing this!

Don't have that much to add, but: I second that!

All the best,
Georg


signature.asc
Description: Digital signature

Re: HTML documentation : work in progress

[Willy Tarreau]

Hi Cyril,

On Mon, Jul 04, 2016 at 12:34:07AM +0200, Cyril Bonté wrote:
> Hi all,
> 
> this was a productive week-end and the new documentation is nearly ready. To
> celebrate this, I've already decided to make it official, despite there is
> stille some work to do.
> 
> The links provided in my previous mail are still working and will become the
> official ones, and everything is also available from the index page :
> 
> http://cbonte.github.io/haproxy-dconv/

I love it! It's really pleasant and convenient to use. The menu on the left
is a nice accelerator because now we can finally lookup parts of words
without ending in random text in the original file! Oh and I just found
that you managed to deduplicate words by sections, excellent :-)

Thanks for doing this!
Willy

Re: HTML documentation : work in progress

[Pavlos Parissis]

On 04/07/2016 12:34 πμ, Cyril Bonté wrote:
> Hi all,
> 
> this was a productive week-end and the new documentation is nearly ready. To
> celebrate this, I've already decided to make it official, despite there is
> stille some work to do.
> 
> The links provided in my previous mail are still working and will become the
> official ones, and everything is also available from the index page :
> 
> http://cbonte.github.io/haproxy-dconv/
> 
> Important change :
> I've decided to remove the search box. It was a funny toy but some people
> reported that they expected it was a full text search box, which was not true,
> and the library behind it looks to not be maintained anymore. To replace the
> feature, I've added tabs at the left : one to navigate in the chapters, 
> another
> to list all the keywords.
> This will allow to use only search tool : the one provided by the browser ;-)
> 
> Now, I'll try to work on less critical tasks :
> - remove the old documentation files and redirect to the new ones.
> - fix the parsing issues I still have at some places (mainly false positives 
> on
> keyword detection).
> - add a filter box in the keywords tab.
> 
> Cheers,
> 
> Le 27/06/2016 à 23:40, Cyril Bonté a écrit :
>> Hi all,
>>
>> It's been monthes since haproxy has introduced new documentation files
>> in 1.6 and 1.7-dev (ie. intro.txt, management.txt, ...). Until now, I
>> hardly found time to include them in the HTML documentation. It's time
>> to seriously work on this issue !
>>
>> There is quite a lot of things to do before I can say everything is
>> ready, but let's go ! This means that things will break for some days.
>> At least, currently I've disabled the job that regenerates the
>> documentations automatically until things become more stable again (New
>> documentation commits won't appear).
>>
>> I'm also thinking of reorganizing the documentation with one directory
>> per major version (1.4, 1.5, 1.6, 1.7).
>>
>> Tasks in the highest priorities :
>> - allow to navigate between files
>> - search keywords in all files
>> - fix rendering issues (I know there are several parts that are not
>> correctly parsed)
>>
>> As an early preview those files are available here :
>> - haproxy 1.4
>> http://cbonte.github.io/haproxy-dconv/1.4/configuration.html
>>
>> - haproxy 1.5
>> http://cbonte.github.io/haproxy-dconv/1.5/configuration.html
>>
>> - haproxy 1.6
>> http://cbonte.github.io/haproxy-dconv/1.6/intro.html
>> http://cbonte.github.io/haproxy-dconv/1.6/configuration.html
>> http://cbonte.github.io/haproxy-dconv/1.6/management.html
>>
>> - haproxy 1.7
>> http://cbonte.github.io/haproxy-dconv/1.7/intro.html
>> http://cbonte.github.io/haproxy-dconv/1.7/configuration.html
>> http://cbonte.github.io/haproxy-dconv/1.7/management.html
>>
> 
> 


Very nice work. I love the ToC at left as I don't need anymore to go the top of
the page to find it :-)

Cheers,
Pavlos




signature.asc
Description: OpenPGP digital signature

Re: HTML documentation : work in progress

[Cyril Bonté]

Hi all,

this was a productive week-end and the new documentation is nearly 
ready. To celebrate this, I've already decided to make it official, 
despite there is stille some work to do.


The links provided in my previous mail are still working and will become 
the official ones, and everything is also available from the index page :


http://cbonte.github.io/haproxy-dconv/

Important change :
I've decided to remove the search box. It was a funny toy but some 
people reported that they expected it was a full text search box, which 
was not true, and the library behind it looks to not be maintained 
anymore. To replace the feature, I've added tabs at the left : one to 
navigate in the chapters, another to list all the keywords.
This will allow to use only search tool : the one provided by the 
browser ;-)


Now, I'll try to work on less critical tasks :
- remove the old documentation files and redirect to the new ones.
- fix the parsing issues I still have at some places (mainly false 
positives on keyword detection).

- add a filter box in the keywords tab.

Cheers,

Le 27/06/2016 à 23:40, Cyril Bonté a écrit :

Hi all,

It's been monthes since haproxy has introduced new documentation files
in 1.6 and 1.7-dev (ie. intro.txt, management.txt, ...). Until now, I
hardly found time to include them in the HTML documentation. It's time
to seriously work on this issue !

There is quite a lot of things to do before I can say everything is
ready, but let's go ! This means that things will break for some days.
At least, currently I've disabled the job that regenerates the
documentations automatically until things become more stable again (New
documentation commits won't appear).

I'm also thinking of reorganizing the documentation with one directory
per major version (1.4, 1.5, 1.6, 1.7).

Tasks in the highest priorities :
- allow to navigate between files
- search keywords in all files
- fix rendering issues (I know there are several parts that are not
correctly parsed)

As an early preview those files are available here :
- haproxy 1.4
http://cbonte.github.io/haproxy-dconv/1.4/configuration.html

- haproxy 1.5
http://cbonte.github.io/haproxy-dconv/1.5/configuration.html

- haproxy 1.6
http://cbonte.github.io/haproxy-dconv/1.6/intro.html
http://cbonte.github.io/haproxy-dconv/1.6/configuration.html
http://cbonte.github.io/haproxy-dconv/1.6/management.html

- haproxy 1.7
http://cbonte.github.io/haproxy-dconv/1.7/intro.html
http://cbonte.github.io/haproxy-dconv/1.7/configuration.html
http://cbonte.github.io/haproxy-dconv/1.7/management.html




--
Cyril Bonté

Re: HTML documentation : work in progress

[Ruoshan Huang]

Thank you!
Having using these html for a long time. I also make a docset for the Dash app, 
if you're a Mac user, it may be handy :). To use it, just search the `User 
Contributed` in preference of the app. All keywords are indexed

> On Jun 28, 2016, at 5:40 AM, Cyril Bonté  wrote:
> 
> Hi all,
> 
> It's been monthes since haproxy has introduced new documentation files in 1.6 
> and 1.7-dev (ie. intro.txt, management.txt, ...). Until now, I hardly found 
> time to include them in the HTML documentation. It's time to seriously work 
> on this issue !
> 
> There is quite a lot of things to do before I can say everything is ready, 
> but let's go ! This means that things will break for some days. At least, 
> currently I've disabled the job that regenerates the documentations 
> automatically until things become more stable again (New documentation 
> commits won't appear).
> 
> I'm also thinking of reorganizing the documentation with one directory per 
> major version (1.4, 1.5, 1.6, 1.7).
> 
> Tasks in the highest priorities :
> - allow to navigate between files
> - search keywords in all files
> - fix rendering issues (I know there are several parts that are not correctly 
> parsed)
> 
> As an early preview those files are available here :
> - haproxy 1.4
> http://cbonte.github.io/haproxy-dconv/1.4/configuration.html
> 
> - haproxy 1.5
> http://cbonte.github.io/haproxy-dconv/1.5/configuration.html
> 
> - haproxy 1.6
> http://cbonte.github.io/haproxy-dconv/1.6/intro.html
> http://cbonte.github.io/haproxy-dconv/1.6/configuration.html
> http://cbonte.github.io/haproxy-dconv/1.6/management.html
> 
> - haproxy 1.7
> http://cbonte.github.io/haproxy-dconv/1.7/intro.html
> http://cbonte.github.io/haproxy-dconv/1.7/configuration.html
> http://cbonte.github.io/haproxy-dconv/1.7/management.html
> 
> -- 
> Cyril Bonté
> 

--
Good day!
ruoshan

Re: HTML documentation : work in progress

[Pavlos Parissis]

On 27/06/2016 11:40 μμ, Cyril Bonté wrote:
> Hi all,
> 
> It's been monthes since haproxy has introduced new documentation files in 1.6
> and 1.7-dev (ie. intro.txt, management.txt, ...). Until now, I hardly found 
> time
> to include them in the HTML documentation. It's time to seriously work on this
> issue !
> 
> There is quite a lot of things to do before I can say everything is ready, but
> let's go ! This means that things will break for some days. At least, 
> currently
> I've disabled the job that regenerates the documentations automatically until
> things become more stable again (New documentation commits won't appear).
> 
> I'm also thinking of reorganizing the documentation with one directory per 
> major
> version (1.4, 1.5, 1.6, 1.7).
> 
> Tasks in the highest priorities :
> - allow to navigate between files
> - search keywords in all files
> - fix rendering issues (I know there are several parts that are not correctly
> parsed)
> 
> As an early preview those files are available here :
> - haproxy 1.4
> http://cbonte.github.io/haproxy-dconv/1.4/configuration.html
> 
> - haproxy 1.5
> http://cbonte.github.io/haproxy-dconv/1.5/configuration.html
> 
> - haproxy 1.6
> http://cbonte.github.io/haproxy-dconv/1.6/intro.html
> http://cbonte.github.io/haproxy-dconv/1.6/configuration.html
> http://cbonte.github.io/haproxy-dconv/1.6/management.html
> 
> - haproxy 1.7
> http://cbonte.github.io/haproxy-dconv/1.7/intro.html
> http://cbonte.github.io/haproxy-dconv/1.7/configuration.html
> http://cbonte.github.io/haproxy-dconv/1.7/management.html
> 


Very nice work, thanks for that.
Pavlos



signature.asc
Description: OpenPGP digital signature

HTML documentation : work in progress

[Cyril Bonté]

Hi all,

It's been monthes since haproxy has introduced new documentation files 
in 1.6 and 1.7-dev (ie. intro.txt, management.txt, ...). Until now, I 
hardly found time to include them in the HTML documentation. It's time 
to seriously work on this issue !


There is quite a lot of things to do before I can say everything is 
ready, but let's go ! This means that things will break for some days. 
At least, currently I've disabled the job that regenerates the 
documentations automatically until things become more stable again (New 
documentation commits won't appear).


I'm also thinking of reorganizing the documentation with one directory 
per major version (1.4, 1.5, 1.6, 1.7).


Tasks in the highest priorities :
- allow to navigate between files
- search keywords in all files
- fix rendering issues (I know there are several parts that are not 
correctly parsed)


As an early preview those files are available here :
- haproxy 1.4
http://cbonte.github.io/haproxy-dconv/1.4/configuration.html

- haproxy 1.5
http://cbonte.github.io/haproxy-dconv/1.5/configuration.html

- haproxy 1.6
http://cbonte.github.io/haproxy-dconv/1.6/intro.html
http://cbonte.github.io/haproxy-dconv/1.6/configuration.html
http://cbonte.github.io/haproxy-dconv/1.6/management.html

- haproxy 1.7
http://cbonte.github.io/haproxy-dconv/1.7/intro.html
http://cbonte.github.io/haproxy-dconv/1.7/configuration.html
http://cbonte.github.io/haproxy-dconv/1.7/management.html

--
Cyril Bonté