Troubleshooting

6. Troubleshooting#

This chapter describes where the connector records what it does and what to do about the problems that occur most often.

6.1. Log file#

The connector writes to /var/log/univention/asm.log. The file holds the debug-level log of every run, including the teachers whom an LDAP filter excluded from a class. The app settings show the time of the last upload in asm/last_upload. asm/last_upload/ACCOUNT holds the time of the last upload to each account.

The log rotation follows the logrotate/* UCR variables of the system. The connector writes its own configuration to /etc/logrotate.d/asm.

Listing 6.1 Follow a synchronization run#
$ tail -f /var/log/univention/asm.log

6.2. Get better error messages from Apple School Manager#

Apple School Manager reports errors in the uploaded data sparsely. The page that shows the SFTP credentials gives more details about the data that Apple School Manager rejects. You can keep the SFTP upload connected.

  1. Open the page with the SFTP credentials, as described in Obtain the SFTP credentials.

  2. Keep the page open and start a synchronization run, as described in Run the synchronization.

The page shows the errors of each upload while the upload runs.

6.3. Users don’t appear in Apple School Manager#

Check the following, in this order:

  1. The user has no primary email address. The connector exports the user without an email address, and Apple School Manager can’t create an Apple Account for the user.

  2. Anonymization removed the email address. Anonymization is enabled by default. With student.anonymize or staff.anonymize enabled for the account, the connector exports the replacement value instead of the address, which is empty by default. See Anonymization.

    Listing 6.2 Turn anonymization off in /etc/asm-connections.json#
    "defaults": {
    "student": {"anonymize": false},
    "staff": {"anonymize": false}
}

  3. The school isn’t on the list. The connector only exports schools that the schools section of the settings file lists, and only to the account that the school refers to. See Schools.

  4. An LDAP filter excludes the user. The log file doesn’t name users whom a filter excluded. Run the filter with univention-ldapsearch to check which users it selects. See Select users with an LDAP filter.

6.4. Apple School Manager rejects an upload without students#

Apple School Manager rejects an upload that contains no student and shows an error. Every account needs at least one student in its upload.

An upload contains no students in the following cases:

  • None of the schools that the account receives has a student.

  • The LDAP filter for students excludes every student of those schools. See Select users with an LDAP filter.

To see the error, follow Get better error messages from Apple School Manager.

6.5. The run stops with a credential error#

The connector stops before it collects any data if /etc/asm-connections.json is missing or invalid, or if a password file is missing or empty. The message in the log file names the file and the entry.

Listing 6.3 Message in the log file#
No Apple School Manager account configured. Create /etc/asm-connections.json as described in the Apple School Manager Connector manual.

Configure the accounts, as described in Apple School Manager accounts. If the credentials are set but Apple rejects them, generate new ones in Apple School Manager and enter those.

6.6. The upload stops with a missing host key#

The connector verifies the host key of the SFTP server against /etc/asm_public_key. The package ships that file. If it’s missing or no longer matches the server, the upload fails with Could not find /etc/asm_public_key or with an SSH exception.

Reinstall the package to restore the file. If Apple changed the host key, report it to Univention, see Where to get help, so that a new version of the app can ship the new key.

6.7. The upload to an account stops with an invalid LDAP filter#

An LDAP filter with a syntax error stops the upload to the account of that school. The connector still uploads to the remaining accounts and exits with a non-zero status at the end. The log file names the filter and the account.

Listing 6.4 Messages in the log file#
Invalid LDAP-filter for students: '(ucsschoolRole=student'
Invalid LDAP filter, nothing uploaded to account north.

Correct the filter in the settings file, or remove the ldap_filter key of the school to fall back to the filter in defaults. See Select users with an LDAP filter.

6.8. Classes have fewer teachers than expected#

Apple School Manager supports at most 15 teachers per class. The connector exports the first 15 and writes a warning to the log file that names the class. This is a limitation of Apple School Manager, not of the connector.

An LDAP filter for teachers can also reduce the number. The log file records every teacher whom a filter excluded from a class.

6.9. Federation for a domain fails the second time#

If you disable federation for a domain and then enable it again, Apple School Manager shows an error.

While federation is on, Apple School Manager offers to disconnect the domain instead of removing it. Disconnecting removes the domain only from the federation. The domain itself stays in Apple School Manager.

To enable federation for the domain again, do the following:

  1. In Apple School Manager, disconnect the identity provider.

  2. Connect it again, as described in Connect the identity provider.

  3. Enable federation for the domain, as described in Enable federation for the domain.

6.10. Where to get help#

  • The Univention Help forum for questions from the community.

  • Your Univention support contract for a supported environment.

When you report a problem, attach the relevant part of /var/log/univention/asm.log.

On this page