Bug 192663 - Incorrect info in handbook for carp on 10+
Summary: Incorrect info in handbook for carp on 10+
Status: New
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: freebsd-doc mailing list
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2014-08-14 18:45 UTC by matt.home
Modified: 2018-03-31 08:09 UTC (History)
3 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 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.