Scott Rotondo wrote: > David Powell wrote: >> When researching the case, I was advised to look at the dladm man >> page. It takes the approach of documenting the necessary profile. >> >> I'm not wedded to either approach, though I have to say that the >> profile has the appeal of being an interface that can be more easily >> maintained in the face of implementation changes. i.e. if the >> previously documented mechanism actually worked, I would have been >> more concerned about changing coreadm from requiring privileges to >> requiring authorizations. If it had been documented in terms of the >> profile, there would be no cause for concern regardless of the >> change. >> >> Given this, the precedent set by dladm, and that in the common case >> coreadm users should just be using the provided profile (i.e. >> referring first to the profile makes the man page more useful >> documentation), would it instead be acceptable to document the >> authorizations in an auxiliary section (e.g. NOTES) leaving the >> profile as the "primary" documented interface? > > So apparently there is more divided opinion on this issue than I > thought. Who would have guessed? ;-) > > I think that individual privilege and authorization names should be the > stable interfaces presented to administrators rather than the names of > RBAC profiles that contain them. My reasons for this view include the > following:
[Reasons I mostly agree with elided] > 4. Privilege names, at least, cannot be considered as implementation > details that are subject to change within an RBAC profile because the > specific privileges are documented on the man pages of system calls that > require them. Although this argument does not apply to authorizations, I > think they should be treated similarly for the reasons described above. But which system calls a command uses to accomplish something are themselves implementation details. It's then our choice whether we expose the privileges those system calls require as privileges the command requires, or we expose an abstraction that hides the underlying authorization mechanism. In other words, though our choice of interface might restrict the system calls we are allowed to use, the choice of system calls doesn't necessarily impact how the command is presented to the user. > Having said all that, this is a general architectural issue that > should not hold up the current fast-track. PSARC members: What is the > best mechanism to reach consensus on this issue and ensure that > current and future documentation complies with that consensus? I don't have a problem with documenting the Authorizations; the reasons for doing so do make a lot of sense. I look forward to your guidance regarding how the different authorization mechanisms should documented. Dave
