Bug 192663

Summary:	Incorrect info in handbook for HAST/CARP
Product:	Documentation	Reporter:	matt.home
Component:	Books & Articles	Assignee:	freebsd-doc (Nobody) <doc>
Status:	Closed FIXED
Severity:	Affects Many People	CC:	allanjude, freebsd, glebius, jrm, pauamma, philipp, rootvg
Priority:	---
Version:	Latest
Hardware:	Any
OS:	Any
Bug Depends on:
Bug Blocks:	263315

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

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

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

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

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(-)