Gnome front-end to freebsd-update
It is a front-end to freebsd-update using GTK+. It will be designed in two parts:
- A daemon that waits for freebsd-update to find new updates
- A GTK+/Gnome front-end
Running
After getting a checkout of the perforce tree you need to build the library and back-end by running make. You can then run the back-end by running:
./backend/facund-be -c backend/freebsd-config-control.conf
To run the front-end you need to be in the frontend directory and run:
python facund.py
You will get a window with a single computer named "Local computer". Click the Connect button. The Connect button should become disabled and the Disconnect button should become enabled. The back-end should write "> facund-client" to the terminal.
When the Disconnect button is pressed the back-end should write "< facund-client" to the terminal.
Back-end
The back-end daemon will find when there are updates available. It will then tell the front-end about the updates that will display them and allow the administrator to install them. It is intended the back-end would be able to be places in the FreeBSD tree. This is to allow other front-end's to be written.
The back-end must be able to run freebsd-update directly, ie. If the freebsd-update script is in a jail the backend will also have to be in a jail.
The back-end should be able to be extended to allow updating of ports/packages and to restart services as required.
Update detection
The back-end will be able to detect when updates have been downloaded and are able to install without calling freebsd-update directly. To do this it will look for the sha256($basedir)-install symlink, where sha256($basedir) is the sha256 of the base directory. Note $basedir will have a newline at the end as it is added by echo.
Detection will be done with kqueue looking for vnode changes on the directory and checking if the symlink exists. It will fall back to polling for the symlink when kqueue is unavailable.
Front-end
The front-end will communicate with one or many back-end daemons. It will be able to notify the administrator when there are updates ready.
The design will allow for multiple back-end's on different computers to allow one front-end to update headless servers.
Communications
The back and front-end's will communicate over either a local IPC or a network connection.
Protocol
Before the front-end can fully communicate with the back-end it must authenticate it's self.
The protocol is based on the back and front ends sending a stream of XML to each other.
Data
A data is sent as the stream:
<data type="type_name">data_value</data>
Type |
Valid data values |
bool |
true, false |
int |
The same range as int32_t |
unsigned int |
The same range as uint32_t |
string |
Any c string. Non-ascii/special characters need to be escaped |
array |
Zero or more data elements |
An example of an array is:
<data type="array"> <data type="int">10</data> <data type="string">Hello, world</data> </data>
When the array would only contain a single item the array data element is unneeded.
Response
After a request the back end sends a response to the front end. The response contains the request id, the return code, human error message and return data. A response looks like:
<response id="rand_id" code="0" message="No error"> <data type="array"> <data type="int">42</data> <data type="string">So long, and thanks for all the fish</data> </data> </response>
Request
A request is used when the front-end needs to ask the back-end to get some data or run a function. A request looks like:
<call name="call_name" id="unique_id">data</call>
The call name is used to indicate what data to send back. The unique ID is used to associate the call with the returned data as it may not be returned until an unknown delay. The data is used when data relating to the request needs to be sent to the back-end.
The following are the valid call names:
Call name |
Valid data |
Description |
Return data |
Back end |
Front end |
ping |
None |
Used to test the connection |
A string containing "pong" |
Yes |
No - Won't be implemented. It was just for testing |
get_directories |
None |
Gets an array of base directories on the system |
An array of base directories |
Yes |
Yes |
list_updates |
A type/directory pair |
Gets a list of updates |
A directory/patchlevel array or false |
Yes |
Yes |
list_installed |
A type/directory pair |
Gets a list of installed patches/packages |
A directory/patchlevel array |
Yes |
Yes |
install_patches |
The patch level to install to |
Installs all patches up to the given level |
|
Yes |
Yes |
rollback_patches |
The patch level to rollback to |
Rolls back to a given patch level |
|
Yes |
Yes |
restart_services |
A string containing one service or an array of strings contain all the services to restart |
Restarts the named rc.d script |
|
No |
No |
When there were two or more data values sent the response will contain an array of the same number of values. eg:
<call name="list_updates" id="1"> <data type="array"> <data type="string">base</data> <data type="string">ports</data> </data> </call>
Would return:
<response id="1" code="0" message="No error"> <data type="array"> <data type="string">p10</data> <data type="bool">false</data> </data> </response>
This means there is the -p10 patch available for the base system and no ports/packages need to be updated.
If the request was just for the base updates it would look like:
<call name="list_updates" id="2"> <data type="string">base</data> </call>
with the response:
<response id="2" code="0" message="No error"> <data type="string">p10</data> </response>
- The type/directory pair is an array with two items. They are:
- A string or an array of strings containing what types of updates are requested.
- A string or an array of strings containing the directories to use.
- The directory/patchlevel data is an array with the following items:
- A string with the current directory
- A string or an array of strings containing the updates, eg. "base" to update the base, "shells/bash" to update the shells/bash port. Only base will be supported to begin with.
Schedule
- Communication protocol: 1 Week
- Back-end: 4 Weeks
- Front-end: 4 Weeks
- Testing: 2 Weeks
- Documentation: 1 Week