Bug 192663 - Incorrect info in handbook for HAST/CARP
Summary: Incorrect info in handbook for HAST/CARP
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks: handbook-2022
  Show dependency treegraph
 
Reported: 2014-08-14 18:45 UTC by matt.home
Modified: 2024-03-15 19:59 UTC (History)
7 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description matt.home 2014-08-14 18:45:38 UTC
Section 18.14.2.1 notes that FreeBSD 10+ users should "replace carp0 with the name of the CARP-configured interface." in the devd rules.

This is incorrect and makes no sense. Using the interface up/down rules are not applicable at all, as carp is configured directly on the real interface. This interface will be up on both master and backup machines in normal operation. The user should use the new CARP devd rules specifically added for this purpose. (As described in carp man page)

Less of an issue, but it also suggests editing /etc/devd.conf. Seeing as a method is provided for the user to add their own rule files, and there appears to be an effort to clean up the base config file (see recent efforts to group rules into /etc/devd/*.conf files), it makes sense to me to tell users to create their own /usr/local/etc/devd/carp.conf file. This provides a concise place to store their carp specific rules and reduces the risk of causing problems in the main devd,conf file.

This should probably be a separate bug but the devd.conf file also needs the CARP rules adding to the list.
Comment 1 matt.home 2014-08-14 18:47:22 UTC
Sorry, in the last line I meant 'man page' not file.
Comment 2 Philipp Erbelding 2016-04-09 13:25:49 UTC
The main issue in this PR is no longer relevant, since the problematic part of the handbook has been rewritten since the PR was opened.

I believe it can/should be closed now.
Comment 3 Allan Jude freebsd_committer freebsd_triage 2016-04-09 17:29:49 UTC
This PR still needs to be addressed. The confusion is the content this PR is talking about is the HAST section (now 18.14), not the CARP section of the handbook

https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/disks-hast.html#idp79156160
Comment 4 Allan Jude freebsd_committer freebsd_triage 2016-04-09 17:30:53 UTC
(In reply to Allan Jude from comment #3)
Sorry, it is now section 17.14.2.1
Comment 5 Karl Sundström 2018-03-31 08:09:32 UTC
I stumbled upon this documentation error as well.

For instance, Hast documentation suggests:

notify 30 {
	match "system" "IFNET";
	match "subsystem" "carp0";
	match "type" "LINK_UP";
	action "/usr/local/sbin/carp-hast-switch master";
};

notify 30 {
	match "system" "IFNET";
	match "subsystem" "carp0";
	match "type" "LINK_DOWN";
	action "/usr/local/sbin/carp-hast-switch slave";
};


But, since you are not using pseudo-devices for CARP anymore, you hook it up to an already existing device, such as em0, the correct example would then be (for VHID 1 on em0):

notify 30 {
        match "system" "CARP";
        match "subsystem" "1@em0";
        match "type" "MASTER";
        action "/opt/scripts/carp-hast-switch master";
};

notify 30 {
        match "system" "CARP";
        match "subsystem" "1@em0";
        match "type" "BACKUP";
        action "/opt/scripts/carp-hast-switch slave";
};


devd.conf documentation has this as an example as well, but its not reflected in the handbook. 

It requires a bit more than just "If the systems are running FreeBSD 10 or higher, replace carp0 with the name of the CARP-configured interface.", becuase it uses CARP system now, instead of CARP as a subsystem.
Comment 6 Gleb Smirnoff freebsd_committer freebsd_triage 2022-02-02 21:56:27 UTC
The problem in documentation still exists.
Comment 7 Pau Amma 2022-06-06 01:12:57 UTC
(In reply to Allan Jude from comment #4)

18.15 now.
Comment 8 Chris Moerz 2024-02-17 12:32:38 UTC
I've posted a review that is addressing this:
https://reviews.freebsd.org/D43948
Comment 9 commit-hook freebsd_committer freebsd_triage 2024-03-15 19:54:23 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=bc3bc049f7e33c6e6a85c19cab03f79c95423b0f

commit bc3bc049f7e33c6e6a85c19cab03f79c95423b0f
Author:     Chris Moerz <freebsd@ny-central.org>
AuthorDate: 2024-03-15 19:19:47 +0000
Commit:     Joseph Mingrone <jrm@FreeBSD.org>
CommitDate: 2024-03-15 19:52:44 +0000

    Handbook/Advanced Networking: Remove obsolete CARP content

    PR:             192663
    Reviewed by:    emaste, jrm, Pau Amma <pauamma@gundo.com>
    Differential Revision:  https://reviews.freebsd.org/D43948

 .../books/handbook/advanced-networking/_index.adoc | 85 +---------------------
 1 file changed, 1 insertion(+), 84 deletions(-)