docu update
[opensuse:yast-rest-service.git] / webservice / README.configuration
1 Configuration
2 ==============
3
4 All configurations should be done in the POST install section of the package.
5
6 After you have installed the package an own lighttpd server with the 
7 YaST-Webservice has been configured which is running with the 
8 system account "yastws".
9 This HTTP server is configured as "localhost" only which has the port 8080.
10 This can be changed in the file /etc/yastws/lighttpd.conf
11
12 So, you can start the server with: "rcyastws start"
13
14 Use the webbrowser with the URL http://localhost:8080
15
16 Login as "root". While the package installation all access rights has been
17 granted to "root". For another users you will have to grant permission as
18 descibed in the following sections:
19
20
21 API Policies
22 ============
23 Each YaST Webservice call has concerning access permissions which can be defined for each user.
24
25 These permissions are handled by PolicyKit in the file:
26
27 /usr/share/PolicyKit/policy/org.opensuse.yast.webservice.policy
28
29 If you are getting a permission error while using the API just have a look to the webserver logfile
30 in order to get the information which permissions are missed:
31
32 Action: org.opensuse.yast.webservice.run-yastmodule User: schubi Result: no
33 Action: org.opensuse.yast.webservice.run-yastmodule-lan User: schubi Result: yes
34
35 These permissions can be set with the call "polkit-auth" like:
36
37 polkit-auth --user schubi --grant org.opensuse.yast.webservice.run-yastmodule-lan
38
39 Or can be reset by:
40
41 polkit-auth --user schubi --revoke org.opensuse.yast.webservice.run-yastmodule-lan
42
43 In order to cleanup or to grant ALL permissions you can use the ruby script policyKit-rights.rb
44 delivered with this package:
45
46    Usage: policyKit-right.rb --user <user> --action (show|grant|revoke)
47    NOTE: This programm should be run by user root
48
49    This call grant/revoke ALL permissions for the YaST Webservice.
50    In order to grant/revoke single rights use:
51    polkit-auth --user <user> (--grant|-revoke) <policyname>
52
53    In order to show all possible permissions use:
54    polkit-action
55
56
57 Roles
58 =====
59 In order to avoid declaring permissions for each user there is the possibility to define roles for
60 each user like: administrator, secretary, ...
61
62 The definition which roles belong to a user are defined in file /etc/yast_user_roles:
63
64 #
65 # file : /etc/yast_user_roles
66 #
67 # This file describes roles of a user accounts for the YaST Webservice
68 # "user accounts": System account which is accessible e.g. via PAM.
69 # "roles"        : Describes user accounts for which policies have
70 #                  been generated
71 #
72 # Format: <user>   <role 1>,<role 2>,...<role n>
73 #
74
75 So, you have to generate a system user e.g. "secretary" and define special right for
76 that user (described above).
77 For getting "secretary" rights you have to add the concerning user in the file 
78 /etc/yast_user_roles only.
79
80 This is a very simple way to store this information. Much more elegant would be to
81 store it to another place e.g. via ldap. Make a proposal :-)
82
83 Hostname and Port
84 ==================
85
86 This settings can be changed in /etc/yastws/lighttpd.conf
87
88 #######################################################################
89 ##
90 ##  Basic Configuration
91 ## ---------------------
92 ##
93 #server.port = 80
94 server.bind = "localhost"
95 server.port = 8080
96
97
98 HTTPS Protocol
99 ================
100
101 SSL
102 -----
103
104 Before we start configuring lighttpd for the YaST-webclient, we’ve got to get an SSL certificate. If you’re creating your own, 
105 you can follow the instructions from the lighttpd web site:
106
107 openssl req -new -x509 -keyout host.pem -out host.pem -days 365 -nodes
108
109 If you already have a certificate that’s a .crt and a .key file, you have to make them snuggle up into a single .pem file:
110
111 cat host.key host.crt > host.pem
112
113 Both of these methods result in a single .pem file, usually named ΄host.pem‘ where ΄host‘ is the name of the server you’re using 
114 the certificate for. This file can be stored anywhere you want on your system, since the lighttpd configuration takes an explicit path to it.
115 Normally certificates are stored in /etc/ssl/certs.
116
117 Configure lighttpd
118 --------------------
119
120 Add these two entries to /etc/yastws/lighttpd.conf
121
122 ssl.engine         = "enable"
123 ssl.pemfile        = "/etc/ssl/certs/host.pem"
124
125 and restart the server with
126
127 rcyastws restart
128
129 Now you can login with HTTPS protocol.
130
131
132 Make it "public" via "avahi"
133 ==============================
134
135 Avahi is a system which facilitates service discovery on a local network. So if it is enabled YaST Webclient 
136 evaluate all available YaST Webservices on a local network automatically and the user can select a service.
137
138 In order to make your YaST Webservice "public" you only have to comment out the entry
139
140 server.bind = "localhost"
141
142 in /etc/yastws/lighttpd.conf and restart the server.
143
144 The startscript rcyastws make the service public while the starting procedure.
145
146 Note: Please be aware that your YaST Webservice is available from outside now. So you should
147 switch to HTTPS-protocol.
148
149
150
151 Starting YaST webservice with webrick (not required)
152 ====================================================
153
154 ROR provides an own webserver called webrick. It is nice for testing but
155 should not used for "realtime".
156
157 Please start this server with the root account.
158
159 Configuration of Webserver rights
160 ------------------------------------
161 These rights are needed for the communication between your webserver and the
162 SCR agent.
163
164 For testing you can grant all permissions to root by adding
165
166 - - - snip - - -
167
168 "http://hal.freedesktop.org/releases/PolicyKit/1.0/config.dtd">
169
170 <!-- See the manual page PolicyKit.conf(5) for file format -->
171
172 <config version="0.1">
173 <match user="root">
174   <match action="org.opensuse.yast.scr.*">
175       <return result="yes"/>
176   </match>
177 </match> 
178 <match user="root">
179   <match action="org.freedesktop.packagekit.system-update">
180       <return result="yes"/>
181   </match>
182 </match>
183 <match user="root">
184   <match action="org.freedesktop.policykit.read">
185       <return result="yes"/>
186   </match>
187 </match>
188
189
190 </config>
191
192 - - - snip end - - -
193
194 to /etc/PolicyKit/PolicyKit.conf
195
196
197 starting
198 - - - - -
199
200 cd /etc/yastws/www/
201 script/server -p 3001
202
203 Logs are written to /etc/yastws/www/log
204
205 first test
206 - - - - - - 
207 Use the webbrowser with the URL http://0.0.0.0:3001
208