Add a section on sudo to the security chapter. This will hopefully be
enough to get most users started. I was wondering about replacing the earlier
blob on it but then chose to just break out an entire new section - thoughts?
Details
Details
- Reviewers
- None
- Group Reviewers
Doc Committers - Commits
- rD48670: Add a section on installing sudo and some basic instruction on the use
Diff Detail
Diff Detail
- Repository
- rD FreeBSD doc repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
There are a very large number of changes, so older changes are hidden. Show Older Changes
| en_US.ISO8859-1/books/handbook/security/chapter.xml | ||
|---|---|---|
| 3955 ↗ | (On Diff #13155) | This whole sentence raises questions for the reader without answering them. When is "at some point"? Or better, why is this needed? What is "managed account escalation"? How about something more definite: System administrators often need the ability to grant enhanced permissions to users so they can perform privileged tasks. Probably can be done better, just winging it. |
| 3959 ↗ | (On Diff #13155) | Better to break the sentence here: ...levels. However, |
| 3960 ↗ | (On Diff #13155) | Passive->active: s/will// |
| 3961 ↗ | (On Diff #13155) | Do we say "superuser" or "super user" elsewhere? Should be consistent with that, and should be in the FDPP word list (it's not). |
| 3969 ↗ | (On Diff #13155) | s/start up/startup/ |
| 3970 ↗ | (On Diff #13155) | s/will/needs to/ |
| 3972 ↗ | (On Diff #13155) | "would manage this" is kind of unclear. Maybe: Traditionally, standard users and groups, file permissions, and &man.su.1; were used to manage this access. |
| 3973 ↗ | (On Diff #13155) | s/as/and as/ |
| 3974 ↗ | (On Diff #13155) | "needed" is redundant with the previous usage in the sentence. Maybe "desired" or "required"? |
| 3975 ↗ | (On Diff #13155) | Since the application name is capitalized, it should be here also. |
| 3977 ↗ | (On Diff #13155) | <para><application>Sudo</application> allows |
| 3978 ↗ | (On Diff #13155) | s/administrations/administrators/ |
| 3979 ↗ | (On Diff #13155) | s/commands,/commands/ |
| 3980 ↗ | (On Diff #13155) | s/ports collection/Ports Collection as <package role="port">security/sudo</package>/ |
| 3981 ↗ | (On Diff #13155) | The end of that sentence can be simplified, and it is not necessary to say "for example": or with &man.pkg.8;. To install the <application>Sudo</application> package:</para> |
| 3982 ↗ | (On Diff #13155) | See note for previous line, "perform the following steps" is not needed. |
| 3986 ↗ | (On Diff #13155) | I suggest that it is not necessary to show users how to install from a package or port for everything. Actually, it is probably counterproductive. Mention the origin of the port (as above), then show installing it as a port or package and call it good. So this sentence can be left out. |
| 3989 ↗ | (On Diff #13155) | "file" is redundant. |
| 3990 ↗ | (On Diff #13155) | I don't know what you mean by "pragmatically" here. Can't it just be can be edited manually or using (may == permission, can == possibility) |
| 3991 ↗ | (On Diff #13155) | Should be <command>, and then the redundant word can be removed: <command>visudo</command>. I would suggest flipping this around. Recommend the right way to do it, then say (if needed) that it can be edited manually. After installation, use <command>visudo</command> can be used to edit <filename>/etc/sudoers</filename>. This file can also be modified with other editors, but <command>visudo</command> checks for configuration errors.</para> |
| 3996 ↗ | (On Diff #13155) | s/mini/small/ |
| 3997 ↗ | (On Diff #13155) | s/allows/allow/ |
| 3998 ↗ | (On Diff #13155) | s/user1/<replaceable>user1</replaceable> Passive->active: |
| 3999 ↗ | (On Diff #13155) | s/webservice/<replaceable>webservice</replaceable>/ |
| 4000 ↗ | (On Diff #13155) | "the following" is not needed here, it's already following. Suggestion: Add this line to the end of <filename>/etc/sudoers</filename>:</para> |
| 4005 ↗ | (On Diff #13155) | "the following" is not needed: The user can start <replaceable>webservice</replaceable> with this command:</para> I'm not sure if the full path to "service" helps make the command clearer or not. And shouldn't that be webservice rather than httpd? |
| 4011 ↗ | (On Diff #13155) | This sentence kind of loses track in the middle. Semicolons are best for long narratives: It was a dark and stormy night. Like a raccoon digging through a trash can, the editor delved through the portions of text. Semicolons were discarded like rotten green peppers; long ago, the existentially-challenged not-a-comma-not-a-period questionableness of these indeterminate punctuation marks had made itself known. Too often, they were used as sentence splices; making sentences longer and more complex (not a good thing for documentation), and a job better done by simpler and more humble punctuation. So: This configuration gives a single user control of <replaceable>webservice</replaceable>. But in most organizations,... |
| 4013 ↗ | (On Diff #13155) | Maybe s/the service/such services/ ? Also: Try to avoid the if/then pause with the comma by reordering: A single line can also give access to an entire group. |
| 4014 ↗ | (On Diff #13155) | s/The following/These/ Passive->active: |
| 4015 ↗ | (On Diff #13155) | "our" is a little unclear. "the"? |
| 4017 ↗ | (On Diff #13155) | This last sentence is not needed. Just jam the colon onto the previous sentence: group to manage the service:</para> |
| 4021 ↗ | (On Diff #13155) | Passive -> active: |
| 4026 ↗ | (On Diff #13155) | Passive -> active: |
| 4028 ↗ | (On Diff #13155) | Since "webservice" is a name, I'd skip the "the" (and also use <replaceable>): ...to manage <replaceable>webservice</replaceable>. |
| 4032 ↗ | (On Diff #13155) | Redundant, and if using the name, capitalize: Unlike &man.su.1;, <application>Sudo</application> |
| 4033 ↗ | (On Diff #13155) | This is a little vague about how it "requires" the user's password. "Unlike" is kind of an "if not", if you see what I mean. Maybe: Users permitted to run applications with <application>Sudo</application> only enter their own passwords. This is more secure and gives better control than &man.su.1;, where the root password is entered and the user acquires all root permissions. (That can be done better, I'm sure. The two things to point out (IMO) are that sudo asks for passwords each time, and that it's the user password.) |
| 4035 ↗ | (On Diff #13155) | Not too clear. <application>Sudo</application> removes the need to deal with the security implications of shared passwords. |
| 4041 ↗ | (On Diff #13155) | "The sudo"? Let's just write it like we'd say it: <application>Sudo</application> provides for these cases |
| 4042 ↗ | (On Diff #13155) | s/by use of/with the/ It's a keyword, though, isn't it? So maybe with the <literal>NOPASSWORD</literal> keyword. |
| 4043 ↗ | (On Diff #13155) | Start the sentence here, like this. Don't need "For example". Also, passive -> active: Adding it to the configuration above allows all members |
| 4044 ↗ | (On Diff #13155) | s/webteam/<replaceable>webteam</replaceable> |
| 4045 ↗ | (On Diff #13155) | End the sentence here: requirement:</para> |
| 4050 ↗ | (On Diff #13155) | Nice to have xml:id set for all sections. It generated anchors that can be linked in URLs. |
| 4054 ↗ | (On Diff #13155) | s/sudo/Sudo/ |
| 4055 ↗ | (On Diff #13155) | "By" is not needed, just "Using" |
| 4058 ↗ | (On Diff #13155) | s/sudo/Sudo/ |
| 4060 ↗ | (On Diff #13155) | Sentence splice or two... and user/uses is confusing. directory entry. This example shows a user variable. However, |
| 4061 ↗ | (On Diff #13155) | Unsplice: several other log filename conventions exist. Consult the |
| 4062 ↗ | (On Diff #13155) | Maybe just say "consult &man.sudoreplay.8;" instead? (Yes, we have a problem with the default link to man pages not including the port man pages. Help to fix that is welcome.) |
| 4068 ↗ | (On Diff #13155) | Not clear whether the program creates the directory or the user is meant to. |
| 4074 ↗ | (On Diff #13155) | Redundant. Not "the sudoers file", better to be just the full path: options inside <filename>/etc/sudoers</filename>.</para> |
| 4079 ↗ | (On Diff #13155) | s/may/can/ |
| 4080 ↗ | (On Diff #13155) | "current" is not clear. How about saying "the previous example can be modified so the <replaceable>webteam</replaceable> has these additional changes:</para>` |
| 4085 ↗ | (On Diff #13155) | s/webteam/<replaceable>webteam</replaceable>/ |
| 4086 ↗ | (On Diff #13155) | Should be "webservice", not plural. And should have <replaceable> tags. |
| 4087 ↗ | (On Diff #13155) | This is one of those if/then "to do this... do this" sentences with a pause at the start. It can be rearranged to avoid the pause: The list of previous and current sessions can be displayed with:</para> |
| 4092 ↗ | (On Diff #13155) | This sentence starts with three separate pausing parts. It's not really clear what it's saying, maybe something like "A specific section of the log can be replayed. Locate the <literal>TSID=</literal> entry in the desired session, then give that value to <command>sudoreplay</command> to replay that session at normal speed:</para> Reader questions: But what is "normal" speed? What exactly does "replay" mean here? Note use of <command> tags. |
Comment Actions
Should I upload another diff at this point or do you just want me to commit the updated version? :)
| en_US.ISO8859-1/books/handbook/security/chapter.xml | ||
|---|---|---|
| 3955 ↗ | (On Diff #13155) | I switched can to "may" here on this one. I can't come up with a different sentence which covers everything I would like so this works. |
| 3959 ↗ | (On Diff #13155) | I think the compound sentence is fine - I really don't want to start a sentence with "however" as it's just odd. I guess the sentence could stand on its own. |
| 3961 ↗ | (On Diff #13155) | Appears to be superuser. Updated. |
| 3970 ↗ | (On Diff #13155) | "needs" has a very odd sound here, used "need" as it still implies the requirement but removes the plural. All else is done here. |
| 3981 ↗ | (On Diff #13155) | I altered to be like: <para>The <application>Sudo</application> application allows administrators to configure more rigid access to system commands and provide for some advanced logging features. As a tool, it is available from the Ports Collection or by use of the &man.pkg.8; tool. To use the &man.pkg.8; tool:</para> <screen>&prompt.root; <userinput>pkg install sudo</userinput></screen> |
| 3989 ↗ | (On Diff #13155) | I'm having a hard time making sense of it without file: "the /etc/sudoers may be ..." |
| 3991 ↗ | (On Diff #13155) | Reworded: <para>After the installation is complete, the installed <command>visudo</command> will open the configuration file with a text editor. Using <command>visudo</command> is highly recommended as it comes with a built in syntax checker to verify there are no errors before the file is saved.</para> |
| 4011 ↗ | (On Diff #13155) | I'll need to come up with something better, there are two independent thoughts here, maybe they should both be fleshed out and made into two or three different paragraphs. |
| 4033 ↗ | (On Diff #13155) | I used yours with added <username> markup. |
| 4061 ↗ | (On Diff #13155) | I removed "however" and split into two sentences. |
| 4062 ↗ | (On Diff #13155) | Ok, what work has been done with the ports manual page link? |
| 4068 ↗ | (On Diff #13155) | Did some fix up here. |
| 4080 ↗ | (On Diff #13155) | I used "in the example shown" and added replaceable markup. |
| 4092 ↗ | (On Diff #13155) | Guess I need to rewrite this paragraph. I was debating on putting in some kind of definition for replay to start with. |
| 4101 ↗ | (On Diff #13155) | This needs re-written. Because while I know that I mean "finding a removed log entry" would leave questions, I can't promise the reader will come to the same conclusion. |
| 4103 ↗ | (On Diff #13155) | I rewrote the paragraph: <warning> <para>While sessions are logged, any administrator is able to remove sessions and leave only a question of why they
had done so. It is worthwhile to add a daily check
through an intrusion detection system (<acronym>IDS</acronym>)
or similar software so that other administrators are alerted
to manual alterations.</para>
</warning> |
Comment Actions
Usually the updated version is added to the review with "update diff". Phabricator loses track when the lines move, but that's the price of improvement, I guess.
Comment Actions
sudo is called sudo, not Sudo, I think it should be lowercased all around. Also, make sure I got all the instances of /etc/sudoers that should be /usr/local/etc/sudoers.
| en_US.ISO8859-1/books/handbook/security/chapter.xml | ||
|---|---|---|
| 3941 ↗ | (On Diff #13684) | It's called "sudo" not "Sudo" (and should be <application>sudo</application>, no ?) |
| 3951 ↗ | (On Diff #13684) | same here. |
| 3977 ↗ | (On Diff #13684) | Drop "the" and "application". |
| 3980 ↗ | (On Diff #13684) | Say it comes from security/sudo with the appropriate markup. |
| 3998 ↗ | (On Diff #13684) | /usr/local/etc/sudoers |
| 4005 ↗ | (On Diff #13684) | shouldn't there be a sudo in there ? like before /usr/sbin/service ? |
| 4022 ↗ | (On Diff #13684) | /usr/local/etc/sudoers |
| 4029 ↗ | (On Diff #13684) | end-user ? |
| 4050 ↗ | (On Diff #13684) | Maybe igor could check that every chapter/sect[12] have xml:id (and maybe sect[34] too. |
Comment Actions
I fixed Mat's points here here except for the "sudo" and "Sudo" thing. As a name, it should be in capitals, and on Todd Miller's site, it's called "Sudo" so I think we can leave it with a capital S. Should I commit now or does anyone want a new diff?
Comment Actions
Update this sudo diff to show I did the work and implemented requested changes. I'll
commit this in a few days if no one else objects.