[PATCH docs] REST API documentation for OpenBMC user management.

[PATCH docs] REST API documentation for OpenBMC user management.

[OpenBMC Patches]

<!-- Reviewable:start -->
This change is [<img src="https://reviewable.io/review_button.svg" height="35" align="absmiddle" alt="Review on Reviewable"/>](https://reviewable.io/reviews/openbmc/docs/19)
<!-- Reviewable:end -->


https://github.com/openbmc/docs/pull/19

Hariharasubramanian R (1):
  REST API documentation for OpenBMC user management.

 obmc-userman.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 obmc-userman.md

-- 
2.7.1

[PATCH docs] REST API documentation for OpenBMC user management.

[OpenBMC Patches]

From: Hariharasubramanian R <hramasub@in.ibm.com>

---
 obmc-userman.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 obmc-userman.md

diff --git a/obmc-userman.md b/obmc-userman.md
new file mode 100644
index 0000000..a5075ca
--- /dev/null
+++ b/obmc-userman.md
@@ -0,0 +1,82 @@
+# User management
+
+User management enables administration of users with different authentication credentials. This provides the foundation for restricting access to REST API based on the user.
+
+In order to access the user management REST API, an initial authentication with *root* credentials is required.
+
+User management provides a *restricted/limited* set of options available through the native Unix user administration commands.
+
+The DBus API for user management is a wrapper over the adduser, deluser, addgrp, delgrp and passwd commands.
+
+## User Management DBus Application, Interface and Objects
+UserManager (phosphor-host-userd) implements the org.openbmc.**Enrol**  interface and exposes the following objects:
+- Groups
+- Group
+- Users
+- User
+
+The Groups object is the container object used to *add* a new group. Likewise Users object is the container object used to *add* a new user. Groups and Users objects also provide the iteration interface to list the members.
+
+The Group object and the User object abstract the individual group/user and hence exposes the method to delete the specific entry and change the password.
+
+## User Management DBus API
+### /org/openbmc/UserManager/Groups Object
+    org.openbmc.Enrol.GroupAddUsr string:"groupname"
+    org.openbmc.Enrol.GroupListUsr
+    org.openbmc.Enrol.GroupListSys
+### /org/openbmc/UserManager/Group Object
+    org.openbmc.Enrol.GroupDel string:"groupname"
+### /org/openbmc/UserManager/Users Object
+    org.openbmc.Enrol.UserAdd string:"comment" string:"username" string:"groupname" string:"passwd"
+    org.openbmc.Enrol.UserList
+### /org/openbmc/UserManager/User Object
+    org.openbmc.Enrol.UserDel string:"username"
+    org.openbmc.Enrol.Passswd string:"username" string:"passwd"
+
+
+## Group Operations and Rules
+
+| Method| Params | Description | Remarks|
+|-------|:------:|-------------|-------:|
+| GroupAddUsr | Group Name | Add a User Group.| GID is automatically selected >= 1000.|
+||||- Group name must be unique.|
+| GroupListUsr || List all User Groups.| List All groups with GID >= 1000.      |
+| GroupListSys || List all Sys Groups. | List All groups with 100 < GID >= 1000.|
+| GroupDel | Group Name | Delete this Group. |Group must have no member users|
+
+
+## User Operations and Rules
+
+| Method| Params | Description | Remarks|
+|-------|:------:|-------------|-------:|
+|UserAdd | GECOS, User Name, Group Name, Password | Add a general User Account.| UID is automatically selected >= 1000.|
+||||User name must be unique and non-empty string.|
+||||Group name, if specified, must be unique and non-empty string.|
+|UserList|| List all general User Accounts.| Users with UID >= 1000.|
+|UserDel |User name| Delete this user. | User name must be non-empty string.    |
+| Passwd | User Name, Passwd | Reset the password of the user to this new passwrod. | |
+
+## Group List semantics
+| Group     | Description  |
+|-----------|--------------|
+| Sys Group | List all groups with 100 < GID < 1000. Common system groups with GID < 100 are hence filtered out in the list.|
+| Usr Group | List all groups with GID >= 1000. These groups are typically those created by a group administration operation.|
+
+## Group Add semantics
+| Group     | Description  |
+|-----------|--------------|
+| Sys Group | Add a group with 100 < GID < 1000, which has system group priveleges.|
+| Usr Group | Add a group with GID >= 1000. These groups are typically those created by an administrator to represent a role.|
+
+## User List semantics
+| User Account | Description  |
+|--------------|--------------|
+| Sys Account  | Not Supported|
+| User Account | List all user accounts with UID >= 1000. These users are typically those created by a user administration operation.
+
+## User Add semantics
+| User/Group   | User Group    | Sys Group     |
+|--------------|---------------|---------------|
+| User Account | Supported     | Supported     |
+| Sys Account  | Not Supported | Not Supported |
+
-- 
2.7.1

Re: [PATCH docs] REST API documentation for OpenBMC user management.

[Jeremy Kerr]

Hi Hari,

> From: Hariharasubramanian R <hramasub@in.ibm.com>
> 
> ---
>  obmc-userman.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Thanks for this! It's great to have this document. A couple of comments.
They're pretty minor though:

The doc makes reference to the REST API, but is this also applicable to
DBUS? If so, we might want to split this up a little:

 - formal DBUS specs should do into the dbus-interfaces.md document

 - informal usage guides can be a separate document

It seems that this is more the latter, which is fine. However, you may
also want to consider adding a spec to the dbus-interfaces doc as an
additional change.

The term 'userman' could be interpreted to mean "User Manual", not "User
Management". We don't really need to contract filenames this much,
calling it something like user-management.md would be fine.

Could you wrap lines at 80 chars? This makes things easier to read in
text form. Also, can you also add a reference to this to the main
README.md doc?

Also, a signed-off-by line is required, to indicate that you've agreed
to the Developers Certificate of Origin.

Cheers,


Jeremy

Re: [PATCH docs] REST API documentation for OpenBMC user management.

[Hariharasubramanian Ramasubramanian]

[-- Attachment #1.1: Type: text/plain, Size: 2072 bytes --]


Hi Jeremy,

Thanks for the comments. I agree with all and will soon update the doc to
address the comments.

I don't quite get what I need to be doing for your last comment:
      Also, a signed-off-by line is required, to indicate that you've
agreed
  to the Developers Certificate of Origin.

Thanks,
rhari !

Hariharasubramanian R.
Power Firmware Development
IBM India Systems & Technology Lab, Bangalore, India
Phone:  +91 80 4025 6950



From:	Jeremy Kerr <jk@ozlabs.org>
To:	openbmc@lists.ozlabs.org
Date:	03/15/2016 08:44 AM
Subject:	Re: [PATCH docs] REST API documentation for OpenBMC user
            management.
Sent by:	"openbmc" <openbmc-bounces
            +hramasub=in.ibm.com@lists.ozlabs.org>



Hi Hari,

> From: Hariharasubramanian R <hramasub@in.ibm.com>
>
> ---
>  obmc-userman.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++
++++++

Thanks for this! It's great to have this document. A couple of comments.
They're pretty minor though:

The doc makes reference to the REST API, but is this also applicable to
DBUS? If so, we might want to split this up a little:

 - formal DBUS specs should do into the dbus-interfaces.md document

 - informal usage guides can be a separate document

It seems that this is more the latter, which is fine. However, you may
also want to consider adding a spec to the dbus-interfaces doc as an
additional change.

The term 'userman' could be interpreted to mean "User Manual", not "User
Management". We don't really need to contract filenames this much,
calling it something like user-management.md would be fine.

Could you wrap lines at 80 chars? This makes things easier to read in
text form. Also, can you also add a reference to this to the main
README.md doc?

Also, a signed-off-by line is required, to indicate that you've agreed
to the Developers Certificate of Origin.

Cheers,


Jeremy
_______________________________________________
openbmc mailing list
openbmc@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/openbmc


[-- Attachment #1.2: Type: text/html, Size: 3160 bytes --]

[-- Attachment #2: graycol.gif --]
[-- Type: image/gif, Size: 105 bytes --]

Re: [PATCH docs] REST API documentation for OpenBMC user management.

[Vishwanatha Subbanna]

[-- Attachment #1.1: Type: text/plain, Size: 3269 bytes --]


For that question : Refer :

https://github.com/openbmc/docs/blob/master/contributing.md

Thanks

-------------------------------------------------------------------------------------

Thanks and Regards,
Vishwanath.
Advisory Software Engineer,
Power Firmware Development,
Systems &Technology Lab,
MG2-6F-255 , Manyata Embassy Business Park,
Bangalore , KA , 560045
Ph: +91-80-46678255
E-mail: vishwanath@in.ibm.com
----------------------------------------------------------------------------------



From:	Hariharasubramanian Ramasubramanian/India/IBM@IBMIN
To:	Jeremy Kerr <jk@ozlabs.org>
Cc:	openbmc@lists.ozlabs.org
Date:	15/03/2016 01:27 pm
Subject:	Re: [PATCH docs] REST API documentation for OpenBMC user
            management.
Sent by:	"openbmc" <openbmc-bounces
            +vishwanath=in.ibm.com@lists.ozlabs.org>



Hi Jeremy,

Thanks for the comments. I agree with all and will soon update the doc to
address the comments.

I don't quite get what I need to be doing for your last comment:
Also, a signed-off-by line is required, to indicate that you've agreed
 to the Developers Certificate of Origin.

Thanks,
rhari !

Hariharasubramanian R.
Power Firmware Development
IBM India Systems & Technology Lab, Bangalore, India
Phone: +91 80 4025 6950

Inactive hide details for Jeremy Kerr ---03/15/2016 08:44:00 AM---Hi Hari,
> From: Hariharasubramanian R <hramasub@in.ibm.com>Jeremy Kerr
---03/15/2016 08:44:00 AM---Hi Hari, > From: Hariharasubramanian R
<hramasub@in.ibm.com>

From: Jeremy Kerr <jk@ozlabs.org>
To: openbmc@lists.ozlabs.org
Date: 03/15/2016 08:44 AM
Subject: Re: [PATCH docs] REST API documentation for OpenBMC user
management.
Sent by: "openbmc" <openbmc-bounces+hramasub=in.ibm.com@lists.ozlabs.org>



Hi Hari,

> From: Hariharasubramanian R <hramasub@in.ibm.com>
>
> ---
>  obmc-userman.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++
++++++

Thanks for this! It's great to have this document. A couple of comments.
They're pretty minor though:

The doc makes reference to the REST API, but is this also applicable to
DBUS? If so, we might want to split this up a little:

- formal DBUS specs should do into the dbus-interfaces.md document

- informal usage guides can be a separate document

It seems that this is more the latter, which is fine. However, you may
also want to consider adding a spec to the dbus-interfaces doc as an
additional change.

The term 'userman' could be interpreted to mean "User Manual", not "User
Management". We don't really need to contract filenames this much,
calling it something like user-management.md would be fine.

Could you wrap lines at 80 chars? This makes things easier to read in
text form. Also, can you also add a reference to this to the main
README.md doc?

Also, a signed-off-by line is required, to indicate that you've agreed
to the Developers Certificate of Origin.

Cheers,


Jeremy
_______________________________________________
openbmc mailing list
openbmc@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/openbmc

_______________________________________________
openbmc mailing list
openbmc@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/openbmc



[-- Attachment #1.2: Type: text/html, Size: 5301 bytes --]

[-- Attachment #2: graycol.gif --]
[-- Type: image/gif, Size: 105 bytes --]