View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Michael J. Flickinger > Sysync-0.31 > sysync


Annotate this POD


View/Report Bugs
Source   Latest Release: Sysync-0.35


sysync - command-line interface for sysync


 usage: ./bin/sysync [--interactive] [command]
    --help (show this)
    --mkpasswd (return password via stdout)
    --passwd=[user] (set a user's password)
    --usersetpassword=[user] allow a user to set their own password
    --usersetpasswordauthkeys returns authorized_keys file for all users to set their password
    --cmd=[host,host2] [command]
    --refresh (alias for --push-auth)
    --push-auth (push auth files to every host)
    --push-files (push controlled files, not auth files, to every host)
 Administrative Commands (using Sysync::File):
    --edithosts (edit hosts.conf file)
    --import-host=[hostname] (returns YAML dump of data from remote host)


Introduction to Sysync

Sysync is a tool to manage users/groups and configuration files across multiple hosts.

Add a user

To get started, first you'll want to create a user account for yourself.

 $ sudo sysync --adduser=yourusername --interactive and you'll see:

 username: elmo
 uid: 1009
 fullname: elmo
 homedir: /home/elmo
 shell: /bin/bash
 disabled: 0
 #gid: (defaults to uid)
 #   - "SSH1 key here"
 #   - "SSH2 key here"
 #   - "SSH3 key here"

Edit the information as you'd like, you can also put multiple ssh keys here per-user.

Now, set the user's initial password:

 $ sudo sysync --passwd=elmo

Next, you'll want to add a group for your user.

Add a group

 $ sudo EDITOR=emacs sysync --addgroup=slackers2 --interactive 
 (in this example, I'm forcing the use of the emacs text editor)

 groupname: slackers2
 gid: 1011
    - elmo
    - elmosbrother

Next, you'll want to setup your default host configuration.

Configure default host

Simply run sysync --edithost=default

You'll see something akin to this in your favorite text editor:

    -  uid: 0
      username: root
      homedir: /root
      shell: /bin/bash
      password: ''
          - "ssh-rsa 1XXX"
          - "ssh-rsa 2XXX"
          - "ssh-rsa 3XXX"
    - { uid: 1, username: daemon, homedir: /usr/sbin, shell: /bin/sh }
    - { uid: 2, username: bin, homedir: /bin, shell: /bin/sh }
    - { uid: 3, username: sys, homedir: /dev, shell: /bin/sh }
    - { uid: 8, username: mail, homedir: /var/mail, shell: /bin/sh }
    - { uid: 10, username: uucp, homedir: /var/spool/uucp, shell: /bin/sh }
    - { uid: 33, username: www-data, homedir: /var/www, shell: /bin/sh }
    - { uid: 34, username: backup, homedir: /var/backups, shell: /bin/sh }
    - { uid: 65534, username: nobody, homedir: /nonexistent, shell: /bin/sh }
    - { uid: 100, gid: 101,  username: libuuid, homedir: /var/lib/libuuid, shell: /bin/sh }
    - { uid: 101, gid: 103, username: syslog, homedir: /home/syslgo, shell: /bin/false }
    - { uid: 102, username: sshd, homedir: /var/run/sshd, shell: /usr/sbin/nologin }
    - { uid: 103, username: ntpd, homedir: /var/run/openntpd, shell: /bin/false }
    - { uid: 104, username: 'Debian-exim', gid: 109, homedir: /var/spool/exim4, shell: /bin/false }
    - { gid: 4, groupname: adm }
    - { gid: 5, groupname: tty }
    - { gid: 6, groupname: disk }
    - { gid: 7, groupname: lp }
    - { gid: 15, groupname: kmem }
    - { gid: 24, groupname: cdrom }
    - { gid: 25, groupname: floppy }
    - { gid: 30, groupname: dip }
    - { gid: 37, groupname: operator }
    - { gid: 40, groupname: src }
    - { gid: 42, groupname: shadow }
    - { gid: 43, groupname: utmp }
    - { gid: 44, groupname: video }
    - { gid: 45, groupname: sasl }
    - { gid: 46, groupname: plugdev }
    - { gid: 50, groupname: staff }
    - { gid: 100, groupname: users }
    - { gid: 101, groupname: libuuid }
    - { gid: 103, groupname: crontab }
    - { gid: 104, groupname: ssh }
    - { gid: 106, groupname: mlocate }
    - { gid: 107, groupname: landscape }
    - { gid: 109, groupname: 'Debian-exim' }
    - { gid: 65534, groupname: nogroup }
 # only import users from the follow groups
 # use all for all users
    - all

You'll want to set your default root password, along with any ssh keys you'd like propagated to the machine.

You'll notice the "user_groups" config, which by default is set to "all". This setting specifies which groups of users should be allowed on the host. 'all' is a special group which imports all users.

Add a host configuration

 You may be interested in generating your host configuration files initially with the --import-host command (see below).

 $ sudo sysync --addhost=spam --interactive

You'll see:

 #   - uid: 0
 #     username: root
 #     homedir: /root
 #     shell: /bin/bash
 #     password: '$6$928b679b70731fc7$OjB.vI0hI4PWC9ObsudW3ITZMBjo7Rfs6Dd5vQ80XZM0A6NU6EQqIVQAI3T90T5Bz3K9Vfha0cp176IAHaNQQ.'
 #     ssh_keys:
 #        - here
 # only import users from the following groups
 # use all for all users
    - all

You can add system users and override users, referenced by the default host image, in this file. For example, you could set a different root password on every host configuration.


    - uid: 0
      username: root
      homedir: /root
      shell: /bin/bash
      password: '$6$928b679b70731fc7$OjB.vI0hI4PWC9ObsudW3ITZMBjo7Rfs6Dd5vQ80XZM0A6NU6EQqIVQAI3T90T5Bz3K9Vfha0cp176IAHaNQQ.'
         - here
 # only import users from the following groups
 # use all for all users
    - sysadmin

In the above example, we're overriding the default password and ssh keys for the root user. We're also only importing members of the sysadmin group.

Import an existing host

Sysync can also create host configurations from existing hosts with the --import-host command.

 $ sudo sysync > host_config.conf

Mapping hosts to hosts

To edit the host mapping:

 $ sudo sysync --edithosts
      - otherhostwouldgohere

Multple physical hosts can be mapped to one host configuration, as seen in the above example.

Controlling files via config

A host configuration file may have a files component, specified as such:

    - file:  /etc/foo.txt
      owner: root
      group: root
      mode:  600
      data: |
         Here is the data.
         It is so awesome.
    - file:   /etc/bar.txt
      owner:  root
      group:  root
      mode:   600
      # uses sysdir, by default /var/sysync/ as base directory if leading slash is omitted.
      source: files/moo.txt
    - { import: host, host: waffle }
    - { import: config, config: files/waffle.conf }

If you import a config, ensure the config is in the following format (the same as if it were in a host file):

    - file:  /etc/foo.txt
      owner: root
      group: root
      mode:  600
      data: |
         Here is the data.
         It is so awesome.

To push changes to files, issue a --push-files command.

SSH keys

Sysync pushes ssh keys under /etc/ssh/authorized_keys/${USERNAME}, if you want to use sysync to manage ssh keys, you'll want to configure sshd_config to use that path:

 AuthorizedKeysFile      /etc/ssh/authorized_keys/%u

Remote password changes

The host running sysync may permit for remote password changes for users.

In this case, we're going to assume this sysync host is not controlling it's own users with sysync.

To configure this:

 1) Setup a user on the sysync host, let's say 'sysync'
 2) Add user to suders:
 sysync ALL=(ALL)NOPASSWD:/usr/sbin/sysync
 3) Setup cron to build authorized_keys file for login:
 $ cat /etc/cron.hourly/sysync-keys
 /usr/sbin/sysync --usersetpasswordauthkeys > /home/sysync/.ssh/authorized_keys
 4) This generates a file like this:
 command="sudo /usr/sbin/sysync --usersetpassword=elmo" ssh-rsa elmosshkeyhere
 command="sudo /usr/sbin/sysync --usersetpassword=elmo" ssh-rsa elmosothershkeyhere
 5) If a user changes their password, sysync pushes it to the relevant hosts.


2012 Ohio-Pennsylvania Software, LLC.


 Copyright (C) 2012 Ohio-Pennsylvania Software, LLC.

 This file is part of Sysync.
 Sysync is free software: you can redistribute it and/or modify
 it under the terms of the GNU Affero General Public License as
 published by the Free Software Foundation, either version 3 of the
 License, or (at your option) any later version.
 Sysync is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 GNU Affero General Public License for more details.
 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <>.


Michael J. Flickinger, <>

syntax highlighting: