Difference between revisions of "Pcad"

From ProgClub
Jump to: navigation, search
(Created page with "Pcad is the ProgClub administration daemon software. That's the software that does various administration things when a non-privileged user asks for them to be done. For example,...")
 
 
(18 intermediate revisions by 3 users not shown)
Line 9: Line 9:
 
Members who have contributed to this project. Newest on top.
 
Members who have contributed to this project. Newest on top.
  
 +
* [[User:SanguineV|SanguineV]]
 
* [[User:John|John]]
 
* [[User:John|John]]
  
Line 15: Line 16:
 
== Copyright ==
 
== Copyright ==
  
Copyright 2011, [[Pcad#Contributors|Contributors]]. Licensed under the [[New BSD license|New BSD]] license.
+
Copyright 2011-2012, [[Pcad#Contributors|Contributors]].
 +
 
 +
== License ==
 +
 
 +
Licensed under the [[New BSD license]].
  
 
== Source code ==
 
== Source code ==
Line 35: Line 40:
 
* [http://blog.emptycrate.com/node/219 Making a Linux Daemon]
 
* [http://blog.emptycrate.com/node/219 Making a Linux Daemon]
 
* [http://www.linuxhowtos.org/C_C++/socket.htm Sockets Tutorial]
 
* [http://www.linuxhowtos.org/C_C++/socket.htm Sockets Tutorial]
 +
* [http://www.paulgriffiths.net/program/c/echoserv.php Simple TCP/IP echo server]
 +
 +
== Functional specification ==
 +
 +
There are two components to this software, the client, and the server.
 +
 +
=== Pcad server ===
 +
 +
The server runs as a daemon process and listens on a TCP/IP port for incoming requests. It parses the requests to find the command. The command must correspond to an executable script in the /etc/pcad/command/ directory. If there is a matching command script then when the server gets a request for that command it runs the corresponding script as root.
 +
 +
=== Pcad client ===
 +
 +
The client is a Linux command that accepts a host, port and command. In the future maybe we'll also support command arguments, but that's not a goal for the first version. So the client might accept a command like this:
 +
 +
$ pcad-request localhost 12345 recreate-test-database
 +
 +
This would send the 'recreate-test-database' command to the pcad server running on the localhost. The server would then receive this command and process the script /etc/pcad/command/recreate-test-database. The pcad-request command blocks until the server has finished processing the request and returns an error level indicating success or error.
 +
 +
There will be another client command, pcad-async, which works the same way as pcad-request except that pcad-async does not block until completion of the command, rather it returns immediately after registering a command with the server, and the server will process the command in the background. The pcad-async command returns an error level indicating an error if the command is invalid, if the command is valid and accepted by the server then the error level is zero.
 +
 +
=== Thoughts ===
 +
 +
Maybe it would be better to give a host name to the client and then have the client lookup the host and port in a config file. For instance there might be a config file in /etc/pcad/client that looks like this:
 +
 +
localhost: localhost 12345
 +
 +
The client could then accept commands for localhost and lookup the host name in the config file to determine which server to connect to. This would simplify client code that needed to be reconfigured to use a different port.
 +
 +
== Technical specification ==
 +
 +
The pcad client commands and the server will be implemented in C.
 +
 +
=== Pcad persistent daemon ===
 +
 +
The pcad server will run as a persistent daemon with something like the following in /etc/inittab
 +
 +
ad:12345:respawn:/usr/local/sbin/pcad-server
 +
 +
To force a reload of the inittab file by the init process:
 +
 +
# kill -HUP 1
 +
 +
=== Pcad network protocol ===
 +
 +
==== Request ====
 +
 +
A request is simply a line of text containing the execution type, followed by a space, followed by the name of the command. The supported execution types are "sync" and "async". So a stream that invoked the recreate-test-database command synchronously would use a network request that looked like this:
 +
 +
sync recreate-test-database
 +
 +
Or if it was an async request:
 +
 +
async recreate-test-database
 +
 +
==== Response ====
 +
 +
A response is a line of text containing the error level, e.g. 0 or 1. After the error level is any text returned on the standard output or standard error streams when the command was run. In the case of an async request the output can be either an error message or nothing.
 +
 +
==== Thoughts ====
 +
 +
There might be a problem with the network connection timing out for long running requests. If the network connection times out the client should return an error level indicating failure. It might be nice to have the server fire up a thread that outputs "." characters every second while the command is being processed. If we do that then the response protocol will have a line of zero or more dots, followed by a line indicating the error level, followed by any output.
 +
 +
=== Security ===
 +
 +
It might be best to run the pcad-server as a user 'pcad' rather than 'root'. This can be done using sudo in the inittab, e.g.
 +
 +
ad:12345:respawn:/usr/bin/sudo -u pcad /usr/local/sbin/pcad-server
 +
 +
The pcad-server would then need to have permission to launch its command scripts as root. This can be accomplished by running the visudo command and adding a line such as the following:
 +
 +
pcad localhost=/etc/pcad/command/*
 +
 +
If we do it this way the server will need to support executing scripts with sudo. We'd also need to make sure that the pcad user didn't have write access to the /etc/pcad/command/ directory.
  
 
== TODO ==
 
== TODO ==
Line 43: Line 121:
 
* Make the executable a managed daemon process that gets started and stopped properly
 
* Make the executable a managed daemon process that gets started and stopped properly
 
* Add support from recreating pcphpjs-dev database
 
* Add support from recreating pcphpjs-dev database
 
[[Category:TODO]]
 
  
 
== Done ==
 
== Done ==
Line 57: Line 133:
 
If you are interested in incorporating the ProgClub pcad into your project, here's what you need to know:
 
If you are interested in incorporating the ProgClub pcad into your project, here's what you need to know:
  
Just copy and paste your way to victory for this one, I think.
+
Just copy and paste your way to victory for this one, I think. You might like to review the code before you use it, I haven't done much programming in C so there might be nasty buffer overflows or other bugs present.

Latest revision as of 16:15, 11 December 2017

Pcad is the ProgClub administration daemon software. That's the software that does various administration things when a non-privileged user asks for them to be done. For example, it can recreate some MySQL databases on your behalf. For other projects see Projects.

Project status

Under way. Not released yet, there's stuff TODO.

Contributors

Members who have contributed to this project. Newest on top.

All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.

Copyright

Copyright 2011-2012, Contributors.

License

Licensed under the New BSD license.

Source code

The repository can be browsed online:

http://www.progclub.org/pcrepo/pcad/

The code for pcad is publicly available from svn:

http://www.progclub.org/svnro/pcrepo/pcad/tags/latest

Or privately available for read-write access:

https://www.progclub.org/svn/pcrepo/pcad/trunk/

Links

Functional specification

There are two components to this software, the client, and the server.

Pcad server

The server runs as a daemon process and listens on a TCP/IP port for incoming requests. It parses the requests to find the command. The command must correspond to an executable script in the /etc/pcad/command/ directory. If there is a matching command script then when the server gets a request for that command it runs the corresponding script as root.

Pcad client

The client is a Linux command that accepts a host, port and command. In the future maybe we'll also support command arguments, but that's not a goal for the first version. So the client might accept a command like this:

$ pcad-request localhost 12345 recreate-test-database

This would send the 'recreate-test-database' command to the pcad server running on the localhost. The server would then receive this command and process the script /etc/pcad/command/recreate-test-database. The pcad-request command blocks until the server has finished processing the request and returns an error level indicating success or error.

There will be another client command, pcad-async, which works the same way as pcad-request except that pcad-async does not block until completion of the command, rather it returns immediately after registering a command with the server, and the server will process the command in the background. The pcad-async command returns an error level indicating an error if the command is invalid, if the command is valid and accepted by the server then the error level is zero.

Thoughts

Maybe it would be better to give a host name to the client and then have the client lookup the host and port in a config file. For instance there might be a config file in /etc/pcad/client that looks like this:

localhost: localhost 12345

The client could then accept commands for localhost and lookup the host name in the config file to determine which server to connect to. This would simplify client code that needed to be reconfigured to use a different port.

Technical specification

The pcad client commands and the server will be implemented in C.

Pcad persistent daemon

The pcad server will run as a persistent daemon with something like the following in /etc/inittab

ad:12345:respawn:/usr/local/sbin/pcad-server

To force a reload of the inittab file by the init process:

# kill -HUP 1

Pcad network protocol

Request

A request is simply a line of text containing the execution type, followed by a space, followed by the name of the command. The supported execution types are "sync" and "async". So a stream that invoked the recreate-test-database command synchronously would use a network request that looked like this:

sync recreate-test-database

Or if it was an async request:

async recreate-test-database

Response

A response is a line of text containing the error level, e.g. 0 or 1. After the error level is any text returned on the standard output or standard error streams when the command was run. In the case of an async request the output can be either an error message or nothing.

Thoughts

There might be a problem with the network connection timing out for long running requests. If the network connection times out the client should return an error level indicating failure. It might be nice to have the server fire up a thread that outputs "." characters every second while the command is being processed. If we do that then the response protocol will have a line of zero or more dots, followed by a line indicating the error level, followed by any output.

Security

It might be best to run the pcad-server as a user 'pcad' rather than 'root'. This can be done using sudo in the inittab, e.g.

ad:12345:respawn:/usr/bin/sudo -u pcad /usr/local/sbin/pcad-server

The pcad-server would then need to have permission to launch its command scripts as root. This can be accomplished by running the visudo command and adding a line such as the following:

pcad localhost=/etc/pcad/command/*

If we do it this way the server will need to support executing scripts with sudo. We'd also need to make sure that the pcad user didn't have write access to the /etc/pcad/command/ directory.

TODO

Things to do, in rough order of priority:

  • Make the executable code run forever
  • Make the executable a managed daemon process that gets started and stopped properly
  • Add support from recreating pcphpjs-dev database

Done

Stuff that's done. Latest stuff on top.

  • JE 2011-09-09: created project page
  • JE 2011-09-09: created project in svn

Notes for implementers

If you are interested in incorporating the ProgClub pcad into your project, here's what you need to know:

Just copy and paste your way to victory for this one, I think. You might like to review the code before you use it, I haven't done much programming in C so there might be nasty buffer overflows or other bugs present.